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

Four kinds of documentation

divio.com

Post reply on HN
Print view View original

141–150 of 203 posts

Re: Four kinds of documentation

#141

Post by pstuart »

franciscop wrote: post #114

I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include: - Project health indicators, all green. [tests | passing] and such. - Quick general description of the problem the project solves. - A simple code snippet showing how easy it is to use it. Not the most complex way of using it as man…

> A simple code snippet showing...

And the variable naming to make clear what is user vs. system defined.

Re: Four kinds of documentation

#142

Post by lelandbatey »

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.

I'll definitely assert that Rust has nailed the automatic generation of documentation from comments in source code. It's a somewhat unusual language so getting used to how the docs are laid out toook a bit of time, but once I was using the language, the docs are the best I've ever used. Some examples:

https://docs.serde.rs/serde_json/

https://doc.rust-lang.org/std/vec/struct.Vec.html

Re: Four kinds of documentation

#143

Post by afarrell »

zomglings wrote: post #81
undergrowth54 wrote: post #22

Earlier quoted context omitted.

> 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.

Writing comments doesn't feel like "writing" to me; It feels like talking.

I've actually written some pretty long comments on reddit. Yesterday, I talked with one of my coaches and put some thought into why:

1) I don't have any memories of feeling anxiousness from commenting on reddit. This is unsurprising since it has never been assigned to me by a teacher/parent. If I ever feel like "Its unclear why I would respond to this or what I would say to this", I just choose not to comment.

2) I have memories of writing a comment and other people upvoting it or telling me that it was helpful. I don't have this for essays. I driven by making people happy, so that is a meaningful reward.

3) Because of those positive memories, as I am writing, I can imagine that a sentence I am about to write is going to be helpful. That imagining is a bit of positive re-enforcement that I can chase, inherent to the task. It is like when I was a kid and I would do math homework and I would solve a problem and see that I'd solved it. It is one of the tricks of TDD.

So, my plan this Saturday is to seek out the things that could possibly be intrinsically rewarding about writing:

A) Look for interesting phrases that I can craft to clearly explain something.

B) When I start on a section, write a question that someone could ask on a reddit thread, which this section answers.

C) When I write a section, imagine myself saying this as an explanation in response to that question and imagine someone else expressing gratitude for that explanation.

D) To avoid procrastination, mentally rehearse the act of starting and getting into the task. Simulate the trigger-response-reward in my mind so I can build the neural pathway. The reward I imagine should not be tied to completion, but come from the "I've just gotten started" state.

Re: Four kinds of documentation

#144

Post by random3 »

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…

My pet-peeve is technical documentation that is not versioned with the code. I think you're confusing garbage-in / garbage-out or interface rendering with auto-"generated" documentation.

Just like you can write bad code, you can write bad docs, not update them etc.

The point of code generated documentation is not to render the interfaces but rather to keep code and docs in sync in the same place. It's more likely you'll se an out of sync / undocumented piece during a code review, in context, etc. then to assume it was updated somewhere else.

Re: Four kinds of documentation

#145

Post by devy »

I like the way the author use Quadrant Analysis (derived from Gartner's Magic Quadrants research methodology[1], well not exactly the same quardrants but similar way of thinking.) to explain the "right" way to do documentation.

[1]: https://www.gartner.com/en/research/methodologies/magic-quad...

Re: Four kinds of documentation

#147

Post by chucksmash »

TuringNYC wrote: post #39
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…

>> Same here. Why is documentation standard so low? Because those who control resources make a conscious decision to prioritize new features and/or bug fixes rather than documenting what exists already.

That's part of it. Plenty of working developers will also omit tests and documentation even without the feature-factory time pressure though. A lot of times, the need for technical documentation isn't even a blip on the TODO radar. If I had a dime for every README where the last change was "Initial commit" and the file only contained

# Service

This is the new service for .

....I could buy a good README.

Re: Four kinds of documentation

#148

Post by Izkata »

degenerate wrote: post #136
zackmorris wrote: post #130

I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at: " rel="nofollow">https://www.php.net/ For example: https://www.php.net/echo Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual. Then there are eve…

Also a major overlooked factor in PHP's documentation success is having a specific URL for each function. Some documentation sites use #anchors to jump to spots in a document (ex: boostrap), but it's not good enough. What ends up happening is people search Google for something granular like "mysql concat" and end up on tutorial sites like w3schools. Why? Because the MySQL documentation throws CONCAT() into a giant me…

> having a specific URL for each function

Which also results in each function having its own comment section, where users can post further examples and pitfalls with that function. These often end up significantly larger and more informative than StackOverflow.

Re: Four kinds of documentation

#149

Post by coldtea »

usrusr wrote: post #119
tootie wrote: post #75

Earlier quoted context omitted.

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.

The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not. Or worse: (pre-)filled with redundant placeholders like "@return returns the $Typename". The frustration pointed out by OP is that when you see a page of "blank" generated documentation you never know if there i…

>The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not.

Still better than 90% of projects/libs at the time, who didn't have any reference documentation at all.

Just seeing the signatures and packages in an organized manner with cross links (e.g. to parent class, implementing classes) etc, was a vast improvement...

Re: Four kinds of documentation

#150

Post by codys »

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.

I've struggled through doxygen generated docs for C++ before, and I think one of the things that helps make javadoc more readable is due to the "stricter" (in a sense) structuring of the java language vs C++: namespaces & objects everywhere make grouping more likely to occur in consistent ways in the code base, which then gets translated to more readable auto-generated documentation.

This is something I think rustdoc (for rust) also has succeeded at, partially for similar reasons.

Post reply on HN