Live data from Hacker News

The tree-based approach to organizing documentation sucks

worldofbs.com

31–40 of 97 posts

Re: The tree-based approach to organizing documentation sucks

#31
I found organizing and finding documentation to be a huge problem ten years ago, not so much now with wikis having decent search. The biggest problem remaining is that it's simply hard to write good documentation, much harder than providing ad-hoc help in person or over Slack.

The reason is that every time you provide an ad-hoc explanation of how something works, you have a concrete context: a person, what they're trying to accomplish, and their understanding. You also have the opportunity to correct course as the person provides immediate feedback in the form of questions and comments. You have a high probability of eventually navigating to positive feedback and a thank-you at the end.

Writing documentation for an abstract audience is much, much harder, and as a result, you will likely hear a lot of negative feedback.

You think you've documented something really thoroughly, and then you hear that it took a recent hire two days to get through it instead of two hours. You start hearing, "This production troubleshooting task was supposed to be documented, but the new person said they had to figure most of it out for themself." WTF? What is "most of it?" You wrote down everything. So you talk to the new person and find out that even though they're a mid-level engineer, they only know Java and have never heard of jq, so for the part that requires pulling some data out of a complicated API response and feeding it to a different API, they wrote a 1000-line Java program complete with tests. You also find out that nobody told them how to make read-only calls to production APIs for troubleshooting purposes (you probably should have linked that info from your documentation) and oh my god in their quest to do this they somehow got their hands on the production API key used by one of the services. Equally horrifying and impressive. So that's what they've been doing for the last two days, because your documentation didn't anticipate the questions they had.

All of that would have become apparent in five minutes on Slack, and it could have been cleared up with a couple of links and examples, but you didn't anticipate any of it when you wrote the documentation. And that's because documentation is hard.

Re: The tree-based approach to organizing documentation sucks

#32
I think of documentation as my little secret superpower. It makes one more productive (i.e. one doesn't need to keep getting interrupted to be asked the same question yet again), it makes others more productive (they can unblock themselves and use the docs to supplement their little corner of tribal knowledge), and good docs allows one to offload knowledge of specifics from one's brain such that just searching for a keyword is sufficient to recall all the nitty-gritty context one needs to fix whatever is the issue at hand.

My general approach is: if a question gets answered in chat, also add it to docs. Personally I dump each question as a markdown header + paragraphs (typically with an error message or uniquely identifiable string in the header), using a FAQ format under whichever page makes the most sense. Then it's easy to find the section w/ the search widget (we use js-search on a next.js SSG site) and it's easy to link to the specific header. Then, the next time the question gets posted on chat, just open docs, search, copy permalink, paste, done.

I agree that making full-fledged, truly useful docs is a lot of work, but you'd also be surprised how much you can get out of relatively little work.

Re: The tree-based approach to organizing documentation sucks

#33

Documentation sucks where no one gets promoted for writing great documentation.

I think it’s actually negative incentive as if you document stuff, you might get questions about it.

I’ve seen the “no documentation = job security” anti pattern for decades. But recently I’ve seen the “if I write something down I can be questioned better by more people so I can lay low by never describing what I’m doing how how you can reuse my libraries and methods.”

It’s a weird situation where people get promoted for “doing stuff” and not for “others doing stuff with my stuff.”

Re: The tree-based approach to organizing documentation sucks

#34
Autogenerated documentation really sucks as well, no matter if it is tree, graph, or wiki based. (Which are all the same thing, in the end)

The bane of my existence in the last 24 hours is a typical example: https://www.freepascal.org/docs-html/current/rtl/fgl/tfpgmap...

There are links that go places, but nothing anywhere actually shows working code examples, or even non-working fragments.

One of the reasons actual civilians were able to write their own programs back in the 1980s was that Turbo Pascal, and Visual Basic had decent manuals, and there were plenty of "dummies" guides as supplements.

Documentation should include working example code for each and every library, function and property supplied.

/End old man rant

Re: The tree-based approach to organizing documentation sucks

#35
post #18

The graph approach (e.g. Wikipedia) is pretty much useless without a search engine (e.g. Google) directing you to the first useful node in the graph. When is the last time you just jumped onto the Wikipedia homepage and found your way to the information you wanted? So 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…

Is "powerful search" really necessary? I feel like you could get by with simple keyword-matching and maybe browse-by-tag

Re: The tree-based approach to organizing documentation sucks

#37
post #8
post #3

>graph based Is it really too uncool to say "hypertext" these days? That's all I'm understanding here. Write docs in hypertext. Otherwise I agree.

Isn't google providing a lot of heavy lifting for wikipedia, by "figuring out" what I want and taking me there. Wiki just on itself, where you need to browse inside to get where you need won't work. Now you need to find the right node in the graph that connects to your information. I feel the same way about Stack Overflow. I rarely search for the answer to my question inside SO, instead google takes me to the relevan…

Hard agree. Finding information on SO has always been much easier for me by asking Google to search there than by using the local search bad.

Re: The tree-based approach to organizing documentation sucks

#38
post #9

I haven't found a good enterprise (for SME's) wiki. Mediawiki is not really usable out of the box without significant work. Obvious stuff is hard to set up, e.g. private wiki with SSO.

I had the same problem and tried a bunch of stuff (mediawiki, confluence, GitHub wiki, gitlab wiki, shared drive, Wordpress, SharePoint) and currently just use GitLab pages because the fork/merge flow for markdown was easier than trying to grant access and moderate a wiki.

It’s still easy to solicit edits, but the issue/question flow is helpful, and have some review process seems to help. Lots of people struggle with git mental models, even using the built in browser IDE in GitLab and GitHub. But most engineers seem to be able to handle.

Re: The tree-based approach to organizing documentation sucks

#39
post #30
post #26

Earlier quoted context omitted.

I like markdown inside the code repo for the precise reason that it is easy to maintain! Also it easy to review ("Hey, this PR should update docs/Testing.md"), and easy to be in sync with what's deployed. At $WORK I've got our repos hooked up to Slab, where the wiki style docs also go, so any search in Slab finds the markdown files as well. And WRT slack, many tools including Slab let you use /slash commands to find…

Sorry, what’s Slab? I couldn’t figure it out by googling “slab source.”

> Slab

I'm guessing, it is https://slab.com/ ("The knowledge base that democratizes knowledge"), which I discovered by searching for "Slab for Slack".

Re: The tree-based approach to organizing documentation sucks

#40
I think the author is missing a key part of why developers often don't like writing documentation but do like answering questions: replacement value.

A developer's compensation is based upon their perceived value (how much it seems like they are needed) and replacement value (how much would it cost to replace them).

A developer that answers questions gets a reputation for helpfulness - this increases their perceived value. Another person needing to go to them to ask questions increases their replacement value too - the more they become the go to person for info, the clearer it is that the company would lose out if it replaced them.

Written docs have almost the opposite effect. Writing amazing documentation doesn't tend to get you a reputation - mostly because it's so depersonalized (does anybody think about the person who wrote a quickstart guide?). It also decreases your replacement value - a fantastically documented project is a project that can be easily handed off to someone else.

I really think that humans get a buzz out of being helpful, too, and you just don't get the feedback that gives you that buzz by writing pages in confluence or whatever. You will likely not even know who found it useful, whereas the dopamine hit you get when somebody asks you a question and you answer it and they click the "heart" button on your slack message is instantaneous.

Post reply on HN