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

61–70 of 97 posts

Re: The tree-based approach to organizing documentation sucks

#61

Post by _y5hn »

more_corn wrote: post #50

The style of the content is often more important than the structure. I've invented a documentation style I call "Notes for Nerds" It consists of the specific notes you make for yourself if you need to re-implement something complicated you've done. It's example driven, very specific and includes only such verbiage as necessary to contextualize the specific technical commands or code. I invented it because I found at…

Title, links, short description and actual copy-paste go a long way. However, it won't dazzle execs.

Re: The tree-based approach to organizing documentation sucks

#63

Post by aequitas »

ryangittins wrote: post #60
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.

And that developer gets fatigued by constantly having to tell others to RTFM, because the documentation is up to date and comprehensive, he took his damn well time to make it so, if they just also took their time to read it, but instead they always ask him anyways or he has to point everything out and at a certain point they just don't care anymore.

Re: The tree-based approach to organizing documentation sucks

#64

Post by ryangittins »

aequitas wrote: post #63
ryangittins wrote: post #60

Earlier quoted context omitted.

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.

And that developer gets fatigued by constantly having to tell others to RTFM, because the documentation is up to date and comprehensive, he took his damn well time to make it so, if they just also took their time to read it, but instead they always ask him anyways or he has to point everything out and at a certain point they just don't care anymore.

It's very true. I think in reality it tends to be a mix—sometimes documentation goes stale, and sometimes people don't even bother reading it regardless of whether or not it's stale.

Another large problem is developers not knowing what they're looking for. Documentation tends to solve the "how I do use this" question and not the "do we already have a solution for this" question.

I'm still not sure how to solve the problem of discovery outside of telling people, "read the docs and hope that someday you'll remember the relevant bits when you need to."

Re: The tree-based approach to organizing documentation sucks

#65

Post by pwdisswordfish0 »

mvanga wrote: 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…

MDN uses a hierarchical structure—a mistake that should have been corrected 10 years ago—and it's awful.

> When is the last time you just jumped onto the Wikipedia homepage and found your way to the information you wanted?

Literally every day. If you haven't done this, the only explanation is that you haven't tried. Wikipedia's built-in search is fine (and also completely unnecessary more often than not, since you can guess most page titles and their URLs). In fact, I've had my browser's default search engine set to Wikipedia for probably 10 years now. If I want to Google something, it's either because I've already hit the Wikipedia article and it was wanting, or it's because I'm looking for something different in nature.

The claim that Wikipedia is junk without Google is itself junk.

Re: The tree-based approach to organizing documentation sucks

#66

Post by ulisesrmzroche »

I don’t know, I think wikis work great. It’s just that writing docs is a lot of work, and like people mentioned here, info decays.

People do without internal docs for the same reason they ship without tests, Pareto principle. And writing is hard work, especially if it’s meant for other people to read.

Cheap, good, and done. Pick 2.

It’s people who don’t keep expectations realistic that wind up going crazy in this industry.

If you want your company to keep nice internal docs, you can’t be cheap. You’ll have to extend deadlines. You have to tell people: I’ll have to add another week for docs and such. Usually, it’s not worth to even bring it up. Why rock the boat?

There’s also the question of how much value they bring, usually not much.

Re: The tree-based approach to organizing documentation sucks

#67

Post by buescher »

majkinetor wrote: post #49

This view is too much simplified. If docs were tree vs graph problem we would probably have at least some orgs doing it right, while there are literarily almost zero. Just few of the missing aspects: 1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seni…

If the FAANG companies started recruiting on ability to communicate in spoken and written English, there'd be a cottage industry in making sure developers weren't functionally illiterate.

Re: The tree-based approach to organizing documentation sucks

#68

Post by [deleted] »

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

[deleted]

Re: The tree-based approach to organizing documentation sucks

#69

Post by pwdisswordfish0 »

prepend wrote: post #38
gomox wrote: 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…

Conjecture: almost every belief that your wiki needs support for ACLs and needs to be moderated (for any reason other than spam) is a belief that's wrong from the start. (And it should be a criminal offense the way that GitHub and GitLab to have corrupted the word "wiki" to be understood to include PR- and review-based workflows centered around big collections of offline source files—the very practice that the wiki was created in reaction to, as a means to solve the problems inherent to that workflow.)

Re: The tree-based approach to organizing documentation sucks

#70

Post by afarrell »

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…

> whereas the dopamine hit you get

But have you ever had a salesperson at the pub tell you about how much easier it is to close deals by pointing to the API integration tutorial you've written?

Hands down, absolutely the proudest accomplishment of my career.

Post reply on HN