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

The Surprising Power of Documentation

vadimkravcenko.com

Post reply on HN
Print view View original

21–30 of 153 posts

Re: The Surprising Power of Documentation

#21

Post by beachy »

bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

> If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.

It sounds like you're thinking about the really boring kind of documentation. The kind that no one wants to read and certainly no one wants to write.

In some approaches, the 4 types of documentation are tutorials, how-to guides, technical reference and explanation.

Any per-screen documentation is not tutorial, how-to or explanation. Perhaps it might be technical reference.

The first question then is why are you working on technical reference? Would you get more bang for the buck writing how-to guides?

Re: The Surprising Power of Documentation

#22

Post by bambax »

onion2k wrote: post #14
bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

What would you do? Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work. I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.

Yeah. There's this quote I love:

> If you have a mountain of shit to move, how much time should you spend looking for a bigger shovel? There's no obviously correct answer - it must depend on the size of the mountain, the availability of large shovels, how quickly you have to move it etc. But the answer absolutely cannot be 100% of your time. At some point you have to shovel some shit.

From https://www.scattered-thoughts.net/writing/things-unlearned/

Re: The Surprising Power of Documentation

#23

Post by bambax »

beachy wrote: post #21
bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

> If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work. It sounds like you're thinking about the really boring kind of documentation. The kind that no one wants to read and certainly no one wants to write. In some approaches, the 4 types of documentation are tutorials, how-to guides, technical reference and explanation. A…

We have docs and videos and whatnot, that describe how to use the application in order to accomplish a given task, in general terms (find some entry in the menu, go there, click that button).

What we do not have is something that describes exactly what the system is supposed to do, so that when one stumbles upon an unexpected behavior, they don't know if it's a bug or if it was intended that way (it could be either, depending on old requirements that weren't properly written down).

Re: The Surprising Power of Documentation

#24

Post by cracrecry »

Mmmm, we believe papers are not enough to document code. We use a lot REPLs in Lisp and python for that.

Most of the time, this means making things smaller and modularise those. It takes a lot of work and there is always an initial resistance from the team for doing it. But it doesn't take much for them to realise how powerful and useful those interfaces are once they are in place and work.

A paper alone with code is kind of dumb, you need something people can interact with by discovery, by doing, experimenting, just like we do as children with the world surrounding us.

Just having some explanation is not enough: People just don't understand things reading about them, but formulating hypothesis about their understanding and confronting those with reality.

Without them, people are not going to be understanding what you believe they are understanding, but their own idea, that is often totally wrong.

Re: The Surprising Power of Documentation

#26

Post by monkeydust »

antupis wrote: post #13

Personally I think at the age of LLM lots of up-to-date documentation will be those superpowers that will boost some companies to whole new level.

Yup.

Were using LLM retrieval methods to build Q&A bots at work. These are all fed with documents (user guides, release notes, transcribed videos etc).

Its still very much POC but the interesting thing is people seems to care about documents again a bit more knowing that it will be used in this manner.

I was thinking about developing something that rewards document producers if their response is cited and used successfully - would help strengthen the feedback loop.

Re: The Surprising Power of Documentation

#27

Post by pixel3234 »

I have moderate successful Java library. Problem with documentation is:

- it takes effort to write it

- there is a split between what documentation describes and reality

- it falls behind as new stuff develops, project gets forked, taken over...

My solution is to have code examples, that are part of unit tests. Separate folder that describes most common use cases. If documentation is wrong, project does not even compile or test fails. And I can always point to most current version of examples in git branch.

I really think any document beyond simple readme.md is overkill for most projects.

Re: The Surprising Power of Documentation

#28

Post by realjohng »

The only place where I’ve seen documentation done well was where it was enforced. For ex: if you’re adding a new analytics tracking event, it must have corresponding documentation in internal wiki or build fails. It was annoying step but it enforced reliability of this wiki.

Re: The Surprising Power of Documentation

#29

Post by eviks »

sarnowski wrote: post #11
eviks wrote: post #8

Earlier quoted context omitted.

another key word is "searchable" documentation, and that's where man pages fail big time leading you to the likes of Google

What degree of „searchable“ are you missing from apropos? https://man.openbsd.org/apropos.1

All of the basics of anything google-like: typo-friendliness with word forms and phrases, links to source, formatting of output, GUI, or not spamming the output with a dozen of lines of warnings that some man page files are missing.

Then a bunch more degrees that I could know about if the tool were more usable

Post reply on HN