Documentation doesn't suck because companies aren't using wikis right. Documentation sucks because it's hard/impossible to do well. Every change to the code can trigger cascading changes in documentation and there's no compiler to tell you which things need to change.
The tree-based approach to organizing documentation sucks
11–20 of 97 posts
Re: The tree-based approach to organizing documentation sucks
#12https://jira.atlassian.com/browse/CONFSERVER-14910
I will almost always shove a bunch of distinct keywords at the bottom of my docs so future searchers can find useful information. This finding information through a log(n) tree search is total bupkis. Relying on others to organize information in the same mental model as you is totally unrealistic.
Re: The tree-based approach to organizing documentation sucks
#13In contrast, your API or your frontend code or your Amazon Lambda or your Microservice is quite likely not feature-complete, does some things that should be handled by a different component and was developed with exactly one use case in mind until it was "good enough". Thanks to scrum, no one cares about completeness, orthogonal design, or composition of smaller parts anymore. Hence documentation has only token value. Except, maybe, for end user documentation, but I am yet to encounter a "user story" that begins with "As a user, I want to do X, read how to do X in the documentation, follow the instructions and get the desired results."
Re: The tree-based approach to organizing documentation sucks
#14What I try to help support on my projects are higher-level block diagrams which show the relationships between major components. Hopefully that doesn't change too quickly! The lower level API should be generated straight from the code itself with a tool like swagger or doxygen if possible.
Re: The tree-based approach to organizing documentation sucks
#15I am hoping to fix this by introducing Optic [0] to automatically handle generating API diffs.
Re: The tree-based approach to organizing documentation sucks
#161. I need an entry point, if things are organized in a graph, then I have no idea where to start. Wikipedia has a landing page. For causal browsing, when I don't have a specific interested topic, I think it's fine. But If I'm new to a code base, I will prefer a start point and a step by step way to understand it. In that case, I think the graph structure fails to serve that purpose. You could create a landing page with a content table, but then that would be the same as the tree model.
2. I won't know the big picture, or the overall scope of a document.
For example, when selecting a third party library, I probably won't think of any caveats that would affect my use case. If I see a caveat section in the content table, I would pay attention to it.
Re: The tree-based approach to organizing documentation sucks
#17It takes a lot of effort to write good documentation. If the documentation is too low-level you get the extreme of "this function adds 1 to x" type comments which don't really help. If the documentation is high-level, many important details can be left out. What I try to help support on my projects are higher-level block diagrams which show the relationships between major components. Hopefully that doesn't change too…
This should be reflected in the documentation.
Re: The tree-based approach to organizing documentation sucks
#18So once you accept that a graph structure is useless without powerful search behind it, the advantages of the tree approach are more obvious: it provides a basic search mechanism through hierarchy, and still allows for a graph approach (via linking and duplication of content in multiple categories).
Also, maintaining documentation sucks. So there's that...
Re: The tree-based approach to organizing documentation sucks
#19Users like outline trees. Trees communicate a lot more information about what the project does and what systems or features support what. Wiki linking, in that case, is just an alternative way to duplicate the content of a page on the tree. Other methods include redirects and using software that can symlink individual blocks of text to keep them in sync. As to why documentation is bad, it's because people close to a…
Re: The tree-based approach to organizing documentation sucks
#20engineers don't hate writing documentation, they hate maintaining it -- even more than they hate maintaining code, which they already don't love even though they love writing it. The OP actually tells that story exactly. They love writing answers in slack precisely because they are ephemeral and targetted at a specific immediate need (which also makes it a lot easier than writing general-purpose documentation btw). B…