The tree-based approach to organizing documentation sucks

Links aren't used for searching, they're used for expanding knowledge on a topic you're already investigating. A personal example: I had to update our metrics infrastructure so I read the existing documentation to understand the way it is done today, and there was a link to our metrics naming spec. I wasn't going to need it but it was still interesting to understand what the conventions are and potentially updating them.

We're using the Atlassian wiki, for which I find search to be very bad so we kind of _have_ to work with links.

IMO documentation exploration can be solved with good search.

Tailwind is a good example of this at https://tailwindcss.com/docs.

The table of contents is worded pretty well but once you get past ground zero of using a tool being able to search for what you want becomes a quick way to find what you're looking for. Especially since the search is powered by Algolia, it's pretty good with full text search.

Thanks, that's indeed the tool. Sorry I should have linked that.

Related to this: understanding the various types of documentation, and using them all appropriately.

I highly recommend Daniele Procida's talk about this, [0] and the accompanying web page [1]. He gives a useful taxonomy of the 4 kinds of documentation. Through the power of Unicode:

    ┌──────────────────────────┬─────────────────────────┐   /\
    │        Tutorials         │       How-to Guide      │   || Practical 
    │    (Learning-oriented)   │    (Problem-oriented)   │   ||
    ├──────────────────────────┼─────────────────────────┤
    │       Discussions        │        Reference        │   ||
    │ (Understanding-oriented) │  (Information-oriented) │   || Theoretical
    └──────────────────────────┴─────────────────────────┘   \/
    
     

[0] https://youtu.be/t4vKPhjcMZg?t=160 (that will take you to the start of the talk proper)

[1] https://documentation.divio.com/

edit Didn't spot the link to [1] at the bottom of the article :P

This view is too much simplified. If docs were tree vs graph problem we would probably have at least some orgs doing it right, while there are literarily almost zero.

Just few of the missing aspects:

1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seniors don't like writing tickets IME which take almost the same time as putting garbage on Slack. I created templates on both GH and GL and almost nobody uses them even tho you don't need to think about anything but follow few rules.

2. Its quite hard to know what level of detail to put in documentation. You need a lot of experience for this - put to much, and it gets quickly outdated, put too little, and it doesn't convey much. Good documentation exists on multiple levels - as bunch of markup files "on the spot", as formal hi and low level documentation and also those are usually affecting different target groups so you actually need to design docs. Cross references are absolutely essential, the docs need to be 100% hyperlinked and in static site format (no big Word or PDF docs really, that should exist only as an export variant). But you also need a tree, because you can just say to people "here is a bunch of docs" just surf around, and good luck". So both tree and graph are required at the same time.

3. Documentation is a service. It has source code, build procedure, automatic link checking, versions, exports to bunch of formats, crosslinks, variables, macros, configuration for different environments, abbreviations, definitions, automation, includes and what not... Its quite hard to get it right. After years of struggle on different projects I finally created my own stuff [1] by bundling many different tools and configs in docker container that I use on all projects, for docs spanning 50-500 pages. I maintain that for years now, constantly (so yeah, its a job).

I am always interested in this as I write tones of docs as a part of system design role. If you have some good ideas to offer, don't hesitate.

[1]: https://github.com/majkinetor/mm-docs-template