[jrochkind1]

engineers 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). But the persistent documentation "just decayed and eventually nobody used it." Exactly.

It's possible the right tools can make it easier to maintain (and thereby less likely to go out of date), but I don't think just simply taking a graph approach is sufficient or a very significant part of it. I'm not sure what that would be -- one obvious answer is tools that generate docs from code or otherwise tie it to code in such a way that when the code changes the docs are forced to change. But while that makes sense, every attempt at this I have seen results in disastrously unfriendly documentation (see eg "relish").

Other approaches are just to capture all that "answer the ephemeral question" documentation that is happening anyway in a way that makes it persistent and more easily searchable. A sort of "knowledge base" approach. (which, true, isn't tree-based). Some of the answers will be out of date when you find them later, but that is expected which somehow makes it less disruptive, and it's still better than nothing.

[julianlam]

I personally find auto-generated documentation based off of code is just awful, unless all you're looking for is the function signature and/or type. Every time I see auto-generated docs, I back out immediately.

The problem I see here is that writing docs when writing code is a different kind of mental activity, and requires some amount of context switching which developers by-and-large are loathe to do.

At least for NodeBB's API[1], we wanted documentation that kept up with changes, so we put in the hours to get a handwritten OpenAPI v3 spec written, and added a rigorous test suite[2] that not only checked syntax, but ensured that all routes defined actually returned a response with the expected schema.

We extended this later on to do the reverse; to check the mounted routes and ensure it is defined in the spec.

It's a pain in the butt when your feature gets pushed and immediately fails API tests, but the tradeoff of having guaranteed up-to-date docs is well worth it.

[1] https://docs.nodebb.org/api/ [2] https://github.com/NodeBB/NodeBB/blob/master/test/api.js

[tln]

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 answers. So in response to a question, you can do a /slab search, and maybe even /slab create to start a stub for a topic.

[prepend]

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

[sfg]

> Slab

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

[tln]

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

[prepend]

Thanks. Comically googling for “slab” didn't show slab.com, although it does now.

[cgenschwap]

You are right that maintaining documentation tends to be the sticking point. The main difference between a graph approach versus a tree approach is the _amount of effort_ required to maintain. If the documentation is incorrect in a tree-based system, say to the point where it is in the wrong place in the hierarchy, it requires a significant amount of effort to fix and maintain. In a graph-based approach it is easier to fix the areas that need to be fixed -- the maintenance burden is lower.

It is also easier to phase out certain documentation, but writing newer, more correct documentation and deprecating the old. Of course this is still possible with a tree-based solution, but there is more flexibility in a graph-based approach.

[sjg007]

Here's your billion dollar slack startup.. create a way to get that slack knowledge into your official documentation.