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

101–110 of 203 posts

Re: Four kinds of documentation

#101

Post by ipsi »

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.

Is that completely true, though? Almost all modern games include a (sometimes optional) tutorial, explaining the basics of how to play the game. Some number (a few? many? most?) of productivity apps will have in-app tutorials to get you up and running. Operating Systems... might have a tutorial? It's been a while sine I booted one up, and I'd likely skip it if present.

On top of that, the GUI nature of these apps makes it easier to get started, I think, and even if there are _no_ tutorials, you can use your previous knowledge of similar apps and play around to understand it - click buttons, tap menus, etc, and learn by doing.

I'm not sure where this fits into the documentation quadrant, but it's important, and is _why_ users can get away without reading documentation.

Re: Four kinds of documentation

#102

Post by eropple »

soulnothing wrote: post #48
Waterluvian wrote: post #29

Earlier quoted context omitted.

When I was super green I argued about this with the principal engineer for quite a while about swagger. Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?

I'm for swagger but only if the router uses it. I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`. Vertx web api contract router. Which takes in a swagger file, and routes based on the `swagger` operation id. Is the closet I've seen. https://vertx.io/docs/vertx-web-api-contract/kotlin I've also written a library to route into ktor in a type safe way. But if you're doin…

> To me it should be written, then consumed by the back-end service.

This is an option, but I find that it works better to have OAS documents generated from what the server is actually doing. Specifying routes based on what the server actually does is, IMO, a more rigorous way to create an OAS spec than to hand-write the spec and then generate a server from it.

I've written a couple of libraries that do exactly this:

https://github.com/eropple/nestjs-openapi3 - OpenAPI3 library for NestJS that standardizes input validation

https://github.com/modern-project/modern-ruby - a Ruby web framework built around OAS3 concepts + rigorous validation

Re: Four kinds of documentation

#103

Post by uhoh-itsmaciek »

commandlinefan wrote: post #60

What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this informatio…

And how it's worse! It's extremely rare, but some projects do tell you, "If you need X, consider Project Y instead."

Re: Four kinds of documentation

#104

Post by otterley »

zomglings wrote: post #89
otterley wrote: post #80

Earlier quoted context omitted.

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.

Yeah, that part was always fine, but they sorely lacked a theory of operations -- which is essential for any sort of state machine or orchestrator! -- and basic "man page"-type documentation around processes, config files, etc.

Re: Four kinds of documentation

#105

Post by luord »

As someone who might be adherent to "good code explains itself", this is a really great explanation of what documentation should actually be and how it should be organized.

It's interesting how one of the projects that I for a long time have believed to have great docs is VueJS, and that documentation more or less adheres to these principles.

Re: Four kinds of documentation

#106

Post by roelschroeven »

commandlinefan wrote: post #60

What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this informatio…

Webpages of many many projects do this very badly. I mostly resort to reading the corresponding wikipedia articles, if any, which often are clearer about what the project does and how it relates/compares to other projects.

Re: Four kinds of documentation

#107

Post by chipotle_coyote »

dtech wrote: post #31
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…

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.

The article talks about four kinds of necessary documentation for large projects: explanation, reference, how-to guides, and tutorials. Auto-generated docs, even when they're very good, only provide one of those -- the reference.

Even if you have great inline documentation that can be turned into a great external reference document, you need separate documentation.

Re: Four kinds of documentation

#109

Post by bluGill »

PeterisP wrote: post #99
Waterluvian wrote: post #29

Earlier quoted context omitted.

When I was super green I argued about this with the principal engineer for quite a while about swagger. Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?

It depends on how you're party to that contract - whether you're involved in making it, or you're a consumer in a take-it-or-leave-it situation. If I'm a consumer of some third-party API, there's no practical difference between intended behavior, accidental mutation and a bug which the supplier won't fix any time soon - all of these things are equally part of the contract of how The Thing v1.2.3 works, and that's wha…

You are mostly correct. However the contract can say "X in the API will change without notice so don't use it", which is valuable to know. Often there are things that must be exposed in the API for "reasons" but the user shouldn't use themselves.

Likewise if v1.2.3 has a bug I want to know to not rely on that because I'll probably update to 1.2.4 which fixes it.

Re: Four kinds of documentation

#110

Post by Crinus »

laumars wrote: post #21
Crinus wrote: post #7

This is a nice article (though i think a bit too wordy). Note that what it calls "tutorial", "how-to guides" and "explanation" is sometimes called "guides", "howtos" and "rationale". As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, c…

> I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library You might be right but I don't remember being impressed with Microsoft's documentation. Half the time if was missing APIs for common useful tasks (there was a big community around demoing undocumented APIs -- granted some were genuinely only intended for internal use but there were some…

I do not think they ever did a good job when it comes to examples, especially in the earlier days. Others like Borland were much better there.

But ever since 3.1 docs you could learn everything you wanted from the help file alone (3.0 help files were reference only) and i mainly refer to their structure. The content was sometimes a miss (though the worst i can remember is not being sure how region object lifetime was managed since unlike other GDI objects there wasn't any function to delete it).

Post reply on HN