Four kinds of documentation • Hacker News Board

Re: Four kinds of documentation

#81

Post by zomglings » Fri, Oct 18, 2019, 2:58 PM UTC

undergrowth54 wrote: post #22

JoeAltmaier wrote: post #13

Earlier quoted context omitted.

Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name a…

> Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing.…

Good luck and, for what it's worth, that was a very well-written comment.

Re: Four kinds of documentation

#82

Post by ojosilva » Fri, Oct 18, 2019, 2:59 PM UTC

tootie wrote: post #75

dtech wrote: post #31

Earlier quoted context omitted.

I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.

I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.

Typedoc [1] is an excellent documentation generator for Typescript.

And every other modern language, be it statically typed or dynamic (with the help of annotations), has had some sort of auto-documentation generator either bundled or at package manager's reach, and probably any can top javadoc in many ways.

[1] https://typedoc.org/

Re: Four kinds of documentation

#83

Post by 725686 » Fri, Oct 18, 2019, 3:00 PM UTC

protomikron wrote: post #49

dtech wrote: post #31

Earlier quoted context omitted.

I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.

> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation. You have to write your docu…

"Does it? You can just alter the code and forget to alter the documentation above the functions/methods"

Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.

Re: Four kinds of documentation

#84

Post by rkangel » Fri, Oct 18, 2019, 3:02 PM UTC

protomikron wrote: post #5

My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the…

Documentation pulled out of code is only as good as the doc comments that have been written. It does have the advantage of making it far easier to write and maintain. If you're editing a function, if the documentation is just above then you're more likely to update it.

This from the Rust standard library is a good example - https://doc.rust-lang.org/std/result/index.html . I think that's great documentation, and it's entirely generated from the source code.

Most rust libraries won't have this level of explanatory detail, the core team have put a lot of effort into making it as easy as possible to learn, and documentation effort is part of that (the Rust book is another important part).

Something else that Rust does well is that 'examples' is a standard part of project layout. For libraries that haven't done their top level documentation well, the examples folder will usually give a good demonstration of how to use the code, and they usually exist because that's the easiest thing for the library author, and the usually compile because they're automatically built by `cargo build`.

Re: Four kinds of documentation

#85

Post by mdtusz » Fri, Oct 18, 2019, 3:07 PM UTC

steveklabnik wrote: post #68

protomikron wrote: post #49

Earlier quoted context omitted.

> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation. You have to write your docu…

With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!

I'm sure you know because you're Steve Klabnik, but for other readers: you can enforce documentation for public items in a crate by adding `#![deny(missing_docs)]` to the `lib.rs` file.

Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.

Re: Four kinds of documentation

#86

Post by kozak » Fri, Oct 18, 2019, 3:09 PM UTC

Bad documentation covers obvious things very well, and doesn't cover tricky parts at all. This is especially what you get if the writer of the documentation is paid by the amount of written text: there is no incentive to spend time investigating the hard parts, but a lot of incentive to explain the easy parts in too much detail.

Re: Four kinds of documentation

#87

Post by LeonB » Fri, Oct 18, 2019, 3:10 PM UTC

With reference docs, I really value the examples.

Describing the syntax, in a formal way is necessary sure. But I often skip down to the examples and that way I get a feel for it quickly.

Bonus points if the examples are thoughtful in the way they start with simple cases and move up to more complex ones while remaining practical and thus easy to imagine their usefulness.

Re: Four kinds of documentation

#88

Post by zomglings » Fri, Oct 18, 2019, 3:11 PM UTC

jpincheira wrote: post #65

Thanks for sharing this guide. It's fitting like a ring to finger as I am in the process of setting up documentation for the features of my app [1] because I realized that as an early-stage startup one of the best ways to teach your users how to use your product is by writing great documentation. I'm finishing the setup of this site within my landing now using Gatsby, on the main domain, so that it can also help to b…

Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia.

As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :)

Thank you for posting the podcast.

Re: Four kinds of documentation

#89

Post by zomglings » Fri, Oct 18, 2019, 3:12 PM UTC

otterley wrote: post #80

kazinator wrote: post #69

> if the documentation is not good enough, people will not use it. Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.

Kubernetes... (although the documentation has gotten better over the years, to the project’s credit) Ruby on Rails as well, for the first few years of its existence.

I always found Kubernetes API reference very useful.

Re: Four kinds of documentation

#90

Post by DanieleProcida » Fri, Oct 18, 2019, 3:12 PM UTC

hanniabu wrote: post #76

DanieleProcida wrote: post #71

Earlier quoted context omitted.

That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs: * tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know wha…

The issue is that tutorials and how to guides signs like the same thing. I prefer to use getting started and how to guides.

I do that sometimes too: https://brachiograph.readthedocs.io/en/latest/get-started/in....