1. 32

  2. 12

    Recognizing that how and why change at different velocities is useful, but their solution to managing the difference is the worst possible I can imagine. Rather than providing documentation on the system and context where the user is working, this approach requires users to leave that context (e.g., the command line) to query another system, in this case, Slack.

    For detailed use cases, doc doesn’t need to be fully contextual. On Unix-like system that’s the point of additional doc in /usr/local/share/doc. But that’s not what we’re talking about here. The examples in the article are for basic usage:

    Question: “How does one use dbconnect to dev vs prod?”

    Answer: Query Slack.

    What’s the user supposed to do when (not if) Slack has an outage? Wait until it’s up again? That’s not a production-friendly answer.

    Again, recognizing the difference between the why and how of documentation is useful. This solution is not.

    1. 3

      Books and legal documents had timestamps and versioning a century before software existed.

      It’s easy to update and commit software documentation and specifications together with the code. (Tools like Bugs Everywhere tried to do the same for bugs as well but unfortunately the popularity of GitHub killed them)

      Documentation does not go stale magically: it does that when is treated as a second class citizen.

    2. 13

      Some great ideas here, but I wish the implementation weren’t so inextricably tied to Slack.

      1. 2

        For what it’s worth, I’ve been chasing a similar idea, though as a single user journaling system, rather than a team knowledge base.

        I’m trying to build low-friction means of recording ideas and things to remember with the ability to give them just enough structure (between searching and tagging) to make it easy to capture ideas and then process them later, when one has the attention for them.

      2. 7

        This sounds horrible. Slack instead of grep. Why not have a README in the dbconnect repo and whoever adds those flags should also update the README. And yeah, whoever notices that it’s not updated should do it and tell the original author that was a bad commit.

        But yeah, maybe I’m just too optimistic and also not working in a huge corporation…

        1. 5

          This is a great example of a light-weight knowledge base for how to do something. I am increasingly of the opinion that a big reason why these types of efforts fail is due to the friction in the process. By “types” I mean efforts such as a knowledge base, service level mapping, ticket/issue management, etc. The rise and success of the wiki is due to the fact that it makes it easy to contribute. The downside of the wiki is that it lacks structure and the content grows stale.

          This example from etsy adds a little more structure to “how-docs” than a wiki by keeping a topical, reverse ordered list of answers. The friction to contribute is about the same as a wiki or maybe even less for those people who are comfortable on a command line.

          1. 1

            Totally agree. I love the concept of wikis but they need some kind of automation to identify stale content. Runnable pages (like Jupyter notebooks) and block-based pages like Notion would be two key features to achieve that, I would say. Do you have any opinion on how wikis could be improved for code documentation?

          2. 4

            I like the idea of a clear separation between how and why, and the attempt to lower the effort required to contribute documentation by hijacking ‘informal’ documentation between team members is neat. However, the way these FYIs are organised sounds like a terrible idea:

            • They assume that each new FYI effectively supersedes previous FYIs.
            • They leave the user to guess how quickly the command has evolved and how fresh is fresh enough to be relevant.
            • What if the first FYI provides the key information about how to use the command, then gets pushed out by specifics about subcommands and flags? The key information is now pushed out of sight at the bottom of the list.
            • What if a fallible human being infiltrates the team and contributes an FYI which isn’t correct?
            1. 5

              I never saw the terms “why-docs” and “how-docs” used before this article, it’s definitely a helpful perspective to approach the complicated issue of having up-to-date, relevant documentation. I like how terminology can help adjust our mental and help us better tackle complex problems.

              1. 3

                When I read this, I thought it was interesting, but at the same time I was kind of appalled at how poorly companies manage their internal documentation. It’s certainly not uncommon as I’ve seen this behavior at just about every company I’ve been at (eBay, Google, Apple, Guidewire, etc.). Apple, perhaps not surprisingly, was the absolute worst of the bunch, since they’ve got internal systems going back decades (and their NIH syndrome and IP paranoia hurt as well). For the others, it varied from group to group, but entropy of internal wikis, etc., were always high.

                I always wished companies would measure the loss of productivity due to outdated internal docs and then use that to justify hiring a dedicated “wiki gardener”, but gave up that fight long ago.

                1. 2

                  It reminds me of IRC bots in popular channels, back in the day. People would teach them about topics, and other people could trigger the bots to search and speak aloud those answers.

                  1. 2

                    I like the idea here, but even more than that I’m fascinated by the idea of using emoji reactions as tagging or webhook target. I had never even considered that before and now wonder what else you could do with that.

                    1. 1

                      Code is constantly changing, so the more code you put into your docs, the faster they’ll go stale.

                      1. Link back and forward between code and the documentation for that code. Even better, use doc comments.
                      2. Check documentation for staleness as part of the code review process.

                      Producing documented, as-correct-as-possible software is our job. Don’t leave it to Slack.

                      1. 0

                        Etsy has some interesting technology. I’m using a variation on their statsd for logging KPIs (Key Performance Indicators) at work. The old method to add a KPI involved several modifications per KPI (and complicated logic in the component to log them every X minutes). The new method you just add them as and where needed.

                        This idea is also great.