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

31–40 of 153 posts

Re: The Surprising Power of Documentation

#31

Post by atoav »

franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically.

Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice.

In my eyes one of the biggest problems with keeping documentation up to date is that over time the mapping between the piece of code you are documenting and the place where you find it in the documentation becomes more complex, to a point where missing something is not unlikely. Rust's documentation-in-code-approach addresses this problem neatly.

Re: The Surprising Power of Documentation

#32

Post by dschuetz »

While I agree that docu is important I've seen my share of garbage poured into wikis and presented as the single source of truth. It takes a lot of time and effort to make docu meaningful and useful with the outlook that it's ignored and overlooked anyways. Quality documentation is expensive, and, if one invests heavily into it there must be a clear workflow path that makes following and reviewing docu mandatory. Documenting for the sole reason of existence of docu is counterproductive.

Re: The Surprising Power of Documentation

#34

Post by rho4 »

In my experience, documentation becomes outdated and fragmented very fast. If I had a say, I would make a rule that every employee should maintain only up to 10 wiki single-pages for their most important products, components or processes. At the top I would require a system overview diagram. And no details, only high-level concepts, keywords, pointers, links and contacts.

Re: The Surprising Power of Documentation

#35

Post by samsquire »

Documentation is where I go to find out the mental model behind the software.

“Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.”

— Fred Brooks

With the mental model of the software, I know where to go, where to look, how to change to fulfil my new requirements.

I am thinking of writing a fictional documentation for a fictional operating system or library or web framework and then see where that design takes me.

Re: The Surprising Power of Documentation

#36

Post by johnnyanmac »

franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

>I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps*

That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much documentation.

But I understand your point. The only thing worse than no documentation is wrong documentation, and outdated docs half the time can become outright wrong half the time, if it isn't simply encouraging outdated but functional practices. Tech writers are highly undervalued for that purpose.

I should also mention that the ability to properly search for docs is almost more important than the doc itself. Some companies had wikis but good luck searching for the right keywords if you didn't know the exact title. A properly categorized top level page could have helped a lot (and is probably easier/cheaper than integrating google like searchabilty into an internal database).

Re: The Surprising Power of Documentation

#37

Post by oneshtein »

rho4 wrote: post #34

In my experience, documentation becomes outdated and fragmented very fast. If I had a say, I would make a rule that every employee should maintain only up to 10 wiki single-pages for their most important products, components or processes. At the top I would require a system overview diagram. And no details, only high-level concepts, keywords, pointers, links and contacts.

Can you show us "definition of done" for your process of closing a ticket? It looks like the "* [ ] update relevant documentation and list link to the documentation changeset" step is missed.

Re: The Surprising Power of Documentation

#38

Post by mailund »

63 wrote: post #19

I'll add that what a lot of non-developers seem to think is documentation is not actually worth very much. For instance, a 2 hour recording of a zoom meeting tagged only with a date and general topic is worth so much less than a searchable text guide on the same topic. Recording a meeting is not documentation! Especially if it's not tagged properly and made available to the people who need it. It's also impossible to…

This is one thing that has always bothered me! A lot of clients ask if I have checked the documentation when I have a very specific question. The documentation however, is just a drive of a bunch of recorded meetings with no tags or transcripts. Am I really supposed to linearly look through tens of hours of recorded meetings to see of the detail might have been mentioned on one of those?

Re: The Surprising Power of Documentation

#39

Post by cjfd »

atoav wrote: post #31
franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.

Re: The Surprising Power of Documentation

#40

Post by elmolino89 »

63 wrote: post #19

I'll add that what a lot of non-developers seem to think is documentation is not actually worth very much. For instance, a 2 hour recording of a zoom meeting tagged only with a date and general topic is worth so much less than a searchable text guide on the same topic. Recording a meeting is not documentation! Especially if it's not tagged properly and made available to the people who need it. It's also impossible to…

I have found that the post meeting notes written by at least two persons then consolidated and improved by others really do help. Recordings while better than nothing would have to have transcripts in order to be usable. Hard to watch hour long recording searching for the relevant 5mins.
Post reply on HN