Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The tree-based approach to organizing documentation sucks

worldofbs.com

Post reply on HN
Print view View original

21–30 of 97 posts

Re: The tree-based approach to organizing documentation sucks

#21

Post by throwanem »

This is good advice, but I'm actually a lot more interested in the "four types of documentation" that it links to: https://documentation.divio.com/

That seems like a super useful categorization, and I intend to use it to inform my own efforts going forward - the first thing I noticed when I looked at this typology was that I generally try to write all of these, and probably the primary barrier to utility in the documentation that I write is that I haven't previously had a good sense of how to separate them out.

Re: The tree-based approach to organizing documentation sucks

#22

Post by sjg007 »

waiseristy wrote: post #12

What's missing here is the effectiveness of the tools search functionality. Confluence does this wonderful thing where, even if you quote the search terms, it will just interpret what it thinks you were trying to search for. You know of a doc that has a very distinct keyword in it? Perhaps "runnable" or something like that? Well too bad, now you have to sift through 500 pages of results for run, running, ran, etc. ht…

I agree confluence is terrible. The tags thing is kind of OK. Gmail fwiw has a similar problem.

Re: The tree-based approach to organizing documentation sucks

#23

Post by area51org »

It's all and none of these things. The single biggest problem with documentation is that it is written by people who are not imagining themselves as the USERS of the software. Typical docs are descriptions of the software, like you'd describe an elephant: here's the trunk, these are what the feet look like. Want to work with an elephant? You're on your own.

Re: The tree-based approach to organizing documentation sucks

#24

Post by endymi0n »

I'll let you in on the biggest unsolved problem in computer science. And no, despite the joke it's neither cache invalidation, naming, concurrency nor off-by-one errors. It's not even handling dependencies.

It's knowledge transfer.

I haven't seen any bigger problem until now and I haven't seen anything that comes close to a solution. Even though, I'm pretty sure of what is not a solution and that is (mid-level) documentation.

Before I go taking that back a notch, let me clarify what I mean with that, as I've seen the cycle numerous times and have been at several of those points myself.

"This is a mess, I don't understand anything... this isn't logical. We need to document everything!

-> Sorry for that bug, I read your docs, but they were outdated.

-> Sorry for that bug, I didn't even bother to read the docs, because most seemed outdated.

-> We'll need to make sure the docs stay current, let's hire a technical writer / wiki gardener / wtf and introduce a process in our "Definition of Done (tm)" so it's all up to date

-> (Actual Development mostly halted by now)

-> Hey, welcome! Oh by the way, before your first commit, please read these 700 pages so we're sure you know what you're doing.

Talented Junior Dev: !!! — Here's my resignation."

The clear exceptions to this casual observation of mine are implicit and high-level documentation.

Implicit includes:

- self-documenting types and code ("Ronseal Code"): https://web.archive.org/web/20170426021541/https://peternixe...

- self-documenting gRPC and Swagger API schema

- self-documenting constraints

- Architecture and Schema diagrams

- Specs and Design Docs

- READMEs

There's only a very limited case where mid-level docs make sense:

- lots of consumers (public & commercial code)

- stable systems with high fluctuation operations

Other than that, this kind of documentation rots far too fast to have much net benefit at a high feature pace.

The only tools that I've consistently seen work so far for knowledge transfer are simply hiring good and communicative people with a learning mindset, keeping attrition low by keeping them happy and productive, intro sessions, code reviews and growing reasonably slow while leveraging junior/senior (as in tenure) pairings for new projects.

No kind of documentation in the world replaces the mental models of the people who architected a piece of software.

Old guy rant end.

Re: The tree-based approach to organizing documentation sucks

#26

Post by tln »

jrochkind1 wrote: post #10

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). B…

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.

Re: The tree-based approach to organizing documentation sucks

#29

Post by prepend »

I hate writing documentation, really appreciate reading great documentation, and hate reading ok or marginal documentation.

My current approach is just to read source only for docs so whatever is in the readme.md and the source files is good enough if a project doesn’t have someone smart who’s into documentation.

And then like “meta docs” generated from markdown in git that links to logs of projects.

Most of the stuff I work on is internal only and even paid people seem to have bad docs as well.

Source + markdown is good enough and seems to attract more internal edits so at least material is more likely to be correct.

Any other scheme seems to fail based on the size of the group so I don’t bother trying to make a specific structure other than “use your judgement, make code readable, make sure any design work not in code is in markdown in the same repo.”

Re: The tree-based approach to organizing documentation sucks

#30

Post by prepend »

tln wrote: post #26
jrochkind1 wrote: post #10

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). B…

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.”
Post reply on HN