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

61–70 of 153 posts

Re: The Surprising Power of Documentation

#61

Post by lisasays »

smeej wrote: post #60

All this assumes one important thing: That people will read what you put in front of them. I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate. People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket t…

People do not read what you write.

Then you need to move on, and find different people.

Yes -- I know it's tough. The landscape out there is quite bleak, in fact.

But these places, and these people do exist.

Re: The Surprising Power of Documentation

#62

Post by barrkel »

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…

This is API reference documentation. What you're missing is conceptual documentation and use case examples.

Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect.

Use case examples string together multiple APIs, multiple domain objects, to achieve a high level business objective. When working on a project, you can sometimes get away without this - the existing code can be example enough to copy. You can end up with cargo culting, people copying things without understanding why. But if you have an API for third-party use, which needs documenting, you need to have either a well-seeded set of open source users, or a great set of examples.

Re: The Surprising Power of Documentation

#63

Post by c00lio »

kristiandupont wrote: post #55
c00lio wrote: post #47

Earlier quoted context omitted.

I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…

It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.

Well, yes, you need to have manual or automatic checks for the presence of the template, and the correctness of the contents is often uncheckable by automated tests. But if things break and e.g. the filled-in documentation template incorrectly said "thread-safe: yes", it will be very easy to 'git blame' the culprit. That way you can at least slowly weed out the sloppy documenters, but I admit that this is tedious.

And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.

Re: The Surprising Power of Documentation

#64

Post by xyst »

smeej wrote: post #60

All this assumes one important thing: That people will read what you put in front of them. I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate. People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket t…

I hate how true this is at most companies I have worked at. Invest a good amount of time writing up the docs and then a few hours later some asshole from another department has the nerve to ask me to “walk me through the process”.

Fuck you. I’ll leave you unread until end of day then send you the docs you clearly didn’t read.

Re: The Surprising Power of Documentation

#65

Post by c00lio »

mailund wrote: post #38
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?

If they are clients or people responsible for any kind of budget, just phrase it as a business offer: I can watch through the 89 hours of relevant documentation in 89 hours for $165 an hour. Pricing fixed if accepted within 2 weeks of offering date.

Re: The Surprising Power of Documentation

#66

Post by c00lio »

revskill wrote: post #30

Suprise ? I thought documentation driven development is already the norm nowdays ? Is there other ways to do software development without documentation first ?

Yes? Think of a few requirements, open an editor and try it out in code. Compile, put in front of users or colleagues, get suggestions, repeat. No docs necessary whatsoever. Half the world works like this.

Re: The Surprising Power of Documentation

#67

Post by arek_nawo »

I believe documentation can be highly beneficial, but only when it's done well. The article makes some good points on this, but, just based on experience and common sense, documentation should be centralized, clean and descriptive enough, while not being too wordy or plain gibberish.

That's not easy to achieve and takes time and resources to get right. That's primarly why so many fail or give up on it.

The results can very much be worth the effort, however, the ones who should be responsible for the documenting process likely don't see its importance. From their perspective, what they've worked on is easy to understand and requires little to no explanation. Taking time to change this mindset and create proper documentation is an effort many are unwilling to take.

Re: The Surprising Power of Documentation

#68

Post by Gwypaas »

barrkel wrote: post #62
atoav wrote: post #31

Earlier quoted context omitted.

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…

This is API reference documentation. What you're missing is conceptual documentation and use case examples. Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect. Use case examples string together multiple APIs, multiple domain objects, to achieve a high level…

Rustdoc supports conceptual documentation quite well, including testing the example code. A specialized page is better, but the pareto principle applies.

See the Clap documentation:

https://docs.rs/clap/latest/clap/

Re: The Surprising Power of Documentation

#69

Post by CharlieDigital »

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

> Imagine working on a codebase where 80% of the code was unused or commented out

That's not documentation; that's code.

Re: The Surprising Power of Documentation

#70

Post by frde »

c00lio wrote: post #47
cjfd wrote: post #39

Earlier quoted context omitted.

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

I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…

Most of what you described as needing documentation could be expressed as code (mixing multiple languages here to express the point more clearly)

const fn get_outer_height() -> Result>

- `const` makes it clear this doesn't mutate

- the function name says exactly what it does

- The return type makes it clear it can return an error

- The return value is typed in a way that makes it clear what the ownership is

Throw in a language like Rust that gives guarantees about thread safety and now the only thing left is if the API is stable or not. Which I would argue doesn't matter much at all since people will still end up depending on it regardless of the comment saying "This API might not be stable"

And the best part? My definition will never get outdated. If the assumptions change, the definition will also need to change (well, except for maybe the name)

Post reply on HN