1. 25
  1.  

  2. 14

    I’m a big fan of storing developer documentation in a doc directory in the git repo, as plain text files in $your_favourite_format. MAny hosting tools will render Markdown (or RST, ASCIIDoc, etc.) But you can also add a static site generator in front of it, which is pretty easy to set up.

    It’s simple, easy, can be reviewed in code reviews, the documentation will always match the code version, can be searched easily, you get a good history with decent tooling (I missed “blame” on Wikipedia many times), anyone can use their $favourite editor/IDE to write documentation, has basically 0 operational overhead/barrier of entry, etc.

    I have yet to see a system that improves on this for developer documentation. Sometimes things don’t need to be complex.

    1. 3

      There was even this cool concept named artifact (now abandoned) that expanded this to provide a link between documentation and implementation of features described in the specification. That sound like almost perfect solution for documenting projects.

      1. 3

        I found this also keep the docs and code in one place so people are easier to update it. Example, you submit a PR and someone pointed out you have to update the doc.

        If we move the doc out to say Google Docs or Dropbox Paper then it’s harder to review them.

        1. 2

          I missed “blame” on Wikipedia many times

          There’s a tool for a git-blame-like usage on Wikipedia http://wikipedia.ramselehof.de/wikiblame.php?lang=en&article=Main_Page (this alternative one also), linked in the History tab for each article.

          Also, putting documentation in the repo makes it easily discoverable with grep for example.

          1. 2

            Ah good to know; thanks. It’s been quite a few years since I did serious editing and I tried to find something like this, but wasn’t able to find it at the time.

          2. 1

            Dropbox Paper worked well at one place, re: operations. Searchable, without having to work out which git repo to look at. Easier to make small edits, without coming up with a edit reason. Editing a wiki page, I could picture getting interrupted, and totally losing the WIP.

            1. 1

              I am also generally a fan of this approach, but unfortunately it still suffers from the same issues as other tree-based solutions. Its fine if it is tied 1-to-1 with the code, because then the hierarchy is determined. But for information that doesn’t fit this mold it has the same issues as any tree-store will.

              Additionally, I have found this approach works until it gets unmaintainable (because tree-based documentation always does), and then someone higher up decides the issue is that the documentation is stored in Git and not the structure of the documentation. I’ve seen this happen twice, and while switching to a system like Confluence makes things worse it is unfortunately how things have gone in my experience.

              Gittit is a cool project which provides a graph/wiki interface on top of a Git repo which I think gets the best of both worlds. As far as I know it doesnt store images in Git which is a little unfortunate though. I would love to see some more solutions in this space, and I’ve been somewhat working on my own on the side.

              1. 3

                I don’t think it needs to be a tree-based approach. I rarely use subdirectories for these things (preferring filenames to order things, like email-development.markdown, email-sendgrid.markdown, etc.) and you can link to other documents with [email-sendgrid] or [See the sendgrid docs](email-sendgrid] (Markdown syntax) which should show up in the rendered version.

                With things like Gittit you lose some of the advantages of storing the docs in the repo, like reviews. We used GitHub wiki at a previous job (which is also stored in git) and I found the only real advantage is the ability to edit files with Vim, which is nice (for me, anyway), but other than that I didn’t really see any clear advantages over Confluence or whatnot.

                The biggest downside of editing Markdown files like this is the lack of direct preview by the way. If you make a typo in the above then you won’t know until after you push, although this can be solved with a doc generator/lint tool locally to some degree (there are other mistakes you can make too, like forgetting to close a * which are not so easily caught by a linter).

                1. 1

                  This is super interesting, thanks for explaining! Using a flat-directory approach with markdown files does seem like a good solution, and I was unaware that Markdown could link between itself that easily. It is certainly something that I will have to try out myself. Have you used this system with many developers at once? I’m curious how easy it is to get everyone on-board.

                  I agree with your points on Gittit; it is not a perfect solution. The underlying behavior is very similar to your flat-directory approach, but the Git integration is a little lacking (for instance, symmetric syncing doesn’t seem completely figured out, and PRs are not a thing).

            2. 8

              I feel like the graph vs. tree thing is something of a false dichotomy. At my workplace, we use Confluence and use its tools to make the information as accessible as possible:

              • Yes, there’s a tree. That’s just how Confluence works
              • We cross link a lot — Confluence makes this easy. In fact, easier than it ever has because the linking dialog you get with cmd-K (on Mac) quickly searches all of the pages for title matches
              • We use tags/labels on pages providing another way to search
              • a top-level page for our engineering docs provides quick searches for those docs, plus the collection of labels

              Our documentation isn’t perfect and, sure, it’s not always obvious where in the hierarchy people should put stuff, but there really are a lot of ways to find information in Confluence.

              1. 3

                I don’t think it is a false dichotomy. Adding links between pages in a tree-based structure might try to approximate the graph structure, but it doesn’t fix the underlying issue. Whatever hierarchy is created will be wrong, and certain documents or information will not fit within it. This means this information is either lost, placed in a poor location or the hierarchy has to go through a restructure. The graph model doesn’t have this issue because there is no inherent structure. There is no hierarchy to get wrong.

                Of course, you can just treat a tree-based documentation system as if it was a graph based system, and use tags/labels, cross-links and a flat hierarchy, but at that point why use the system over something that is designed to support that use-case?

                1. 3

                  Q: What’s the difference between a tree-based structure and an index of pages/sections where the index is organised by category and the category has subcategories (usually numbered, e.g. 3.2.1)?

                  Perhaps the difference is if you mandate creating the index first, rather than it being a future summary of existing material? Perhaps the correct term is graph-first vs tree-first?

                  1. 1

                    Q: What’s the difference between a tree-based structure and an index of pages/sections where the index is organised by category and the category has subcategories (usually numbered, e.g. 3.2.1)?

                    If I’m understanding you correctly they are effectively the same thing. Textbooks, for instance, are tree-based structures.

                    Perhaps the difference is if you mandate creating the index first, rather than it being a future summary of existing material? Perhaps the correct term is graph-first vs tree-first?

                    The issue is that an index is only going to be correct at a specific snapshot in time. Unlike textbooks, company documentation is a living entity that changes over time (although textbooks do have revisions). Once a tree-like index is added to the documentation it will eventually become out-of-date and require redoing, or cause the documentation to rot.

                    It doesn’t really matter when the index is added, I think we should attempt to avoid it completely. The alternative in a graph-based documentation system is to have categories and tags, with the main difference being that a single page can be in multiple categories or have multiple tags.

              2. 6

                “Ad Hoc Documentation” is also different from “Real Documentation” because it’s situational. I don’t have to write to whoever doing whatever. I’m writing for cgenschwap and they’re trying to make the authored-by flag work. That makes the problem you’re solving fundamentally different, and I think that has as much to do with it as graphs-vs-trees does.

                I hate writing documentation because I never no how much to write down. Too much, and it becomes an incomprehensible deluge. Not enough, and it’s useless.

                1. 3

                  You’re right, ad-hoc documentation can be situational. However I’ve found many cases to be of the form “Oh, X happens all the time with Y, just do A, B and C to resolve it.” While this is ad-hoc, it can and should exist as a how-to or runbook in the documentation – its a known situation with a known resolution. There are definitely situations where it is highly specific, but I think those are fairly rare (for instance, that information can always go into a “Troubleshooting” section).

                2. 3

                  I think that the graph approach’s success really hinges on a solid search engine for your documentation. Otherwise, if when searching for something 50 pages comes out, you might be worse off finding the right one than if could go through a hierarchy.

                  1. 3

                    Yes and no. I think a simple keyword matching search is all that is needed, which every graph-style documentation system has. A graph-based system also does not prevent you from using categorization, which both Wikipedia and the Arch Linux Wiki rely on as well, which allows you to have a “categorization” page which links to many different pages. This is an extremely flexible system, as pages can be in multiple categories with no issue.

                  2. 1

                    Trees were never the right solution, but that doesn’t mean they’re not useful. I think that, even for file systems, a better solution would be a tag-based system from which trees can be constructed on-demand based on some set of tag groups. This doesn’t preclude a graph interface, as the value of a tag can be another node.

                    1. 1

                      I agree trees can be useful. The benefit of organizing knowledge in a graph is that you can then make arbitrary spanning trees representing hierarchies. This is flexible because you can make different trees for different situations (tags and categories are like this), and remove them if they are no longer relevant.

                      A tree based store doesn’t have the same flexibility.