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

51–60 of 97 posts

Re: The tree-based approach to organizing documentation sucks

#51

Post by pydry »

erikerikson wrote: post #46
pydry wrote: post #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…

There's another perspective to take on this. This sort of behavior you are describing locks you further and further into the role you are in right now, reducing the rate of which you grow and learn. It sets up by dynamic where the company is incentivized to keep you there. Another possibility is that you make yourself entirely removable or even just solve the problem so well that it no longer needs headcount. Instead…

I've worked with the kind of developers who try to gatekeep their knowledge and the systems they work with. I find that a few of the following conditions tend to hold:

* They're not very good developers and not very smart and probably somewhat cognizant of that.

* They're afraid of interviewing.

* They're working in smaller markets (e.g. a town which has maybe just one or two companies that hire developers).

* They're spending right up against their income or beyond it and are afraid of losing their job.

If they hit all of these checkboxes then I reckon this behavior is almost guaranteed and getting potentially "redundancy inducing information" out of them will be like pulling teeth. They'll be busy a lot. Far too busy to talk to you. Their docs likely won't be nonexistent (too obvious), but they will probably be deliberately obtuse.

They're primarily concerned not with learning but with not losing their primary source of income and their time horizon shortens, much like it does for those stuck in a behavioral poverty trap https://www.sciencedirect.com/science/article/abs/pii/S03043...

Yes, this sort of behavior locks you further and further into the role you are in and is possibly self defeating, but it's entirely natural and fairly common.

Re: The tree-based approach to organizing documentation sucks

#52

Post by erikerikson »

The integration work is what's hard. Just like it's easier to cut new code and harder to resolve conflicting needs in two existing systems. Cleaning up the mess of how two things have moved forward under different incentive systems and for different purposes, that's the nasty stuff and the hard work. The accumulated disynchrony is what makes documentation suck and reduces the value of referencing it which can be a death spiral when it thereby reduces the value of producing it.

This article reminds me of the challenges of an object-oriented decomposition of a system. The solution being something like adding aspects (see AOP), relationship links with metadata, and, sure, adding a graph structure.

However, I would suggest that reducing the space between a documentation system and the code base it is documenting is one of the deeply important missing pieces. What belongs on a distilled documentation page versus in the code is the spectrum. We have data formats listed in our documentation but those should be links to the schemas (and maybe examples) in our code base.

Re: The tree-based approach to organizing documentation sucks

#53

Post by jimduk »

choeger wrote: post #13

Documentation sucks because nothing is used very often anymore. In the good old days (TM), software was used for much longer in pretty much the same shape. Think of GNU coreutils. In 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 min…

Agreed, and I would add pre-web well authored Microsoft help files/ hypertext were often really valuable and could be very well done. Also you could build them after the software was done, or before, as the spec in progress. Think msft help was one of the unsung heroes of their success. But if you have changing software Google/SO is much faster. (Disclaimer, used to work on 'performance support' systems late 90s, one of the points of focus was how do you help users keep improving their combined tool use, team performance and business understanding)

Re: The tree-based approach to organizing documentation sucks

#54

Post by majkinetor »

lhorie wrote: post #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…

I have similar approach. If I can't send you think link on Slack, its not good enough. If you don't understand, I update the docs and send you the link/diff again.

Re: The tree-based approach to organizing documentation sucks

#55

Post by cgenschwap »

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…

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.

Re: The tree-based approach to organizing documentation sucks

#56

Post by julianlam »

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 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

Re: The tree-based approach to organizing documentation sucks

#57

Post by ebiester »

area51org wrote: post #23

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.

I think the article is talking about internal documentation rather that user-facing documentation.

Re: The tree-based approach to organizing documentation sucks

#58

Post by RandallBrown »

CobsterLock wrote: post #11
RandallBrown wrote: post #2

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.

dont most enterprise languages have built in docs that do a basic type check? I'm thinking of something like JavaDocs and MS Docs for C#, that at the very least have built in typing for explicit references to objects. But i do see the breakdown quickly happening when you informally reference concepts. I have been trying to push for getting as much documentation inside the actual code as possible and auto-generating a…

I don't know about most, but things like JavaDocs are certainly pretty common.

That's not really what we're talking about here though. Like you said, it's the concepts and informal stuff that's the problem.

I've found autogenerated stuff to only be marginally more helpful than just reading the code in the first place.

Re: The tree-based approach to organizing documentation sucks

#59

Post by prepend »

sfg wrote: post #39
prepend wrote: post #30

Earlier quoted context omitted.

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".

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

Re: The tree-based approach to organizing documentation sucks

#60

Post by ryangittins »

pydry wrote: post #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…

This is an interesting point! I do think there's another factor at play here, though: documentation goes stale.

When you've been burned by stale documentation (or any tool) enough times, you can start to lose trust in it. When you lose trust in documentation, you second-guess it and often pursue a a live, fresh second opinion from another developer with more knowledge anyway.

Post reply on HN