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

31–40 of 203 posts

Re: Four kinds of documentation

#31

Post by dtech »

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.

Re: Four kinds of documentation

#32

Post by dragonwriter »

michannne wrote: post #24
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…

Because docs take time to write, and good docs require a passionate dev who cares to write them

Good docs take a dedicated tech writer who cares to write them. A passionate dev may or may not be a decent tech writer.

Re: Four kinds of documentation

#33

Post by dtech »

Waterluvian wrote: post #29
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…

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?

A separate specification works much better as long as that specification is also enforced during the build.

A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.

Re: Four kinds of documentation

#34

Post by the_af »

michannne wrote: post #24
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…

Because docs take time to write, and good docs require a passionate dev who cares to write them

...plus they tend to get outdated and out of sync with the code pretty fast!

Re: Four kinds of documentation

#35

Post by the_af »

protomikron wrote: post #14
Consultant32452 wrote: post #11

Earlier quoted context omitted.

I use javadocs all the time. Those are generated off comments in code. Is that the kind of thing you mean?

Yes. Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like: public class BookStore { ... /** * @param book The book. * @return The price. */ public static float getPrice(Book book) { return book.price() } } No shit sherlock! I admit that this is a contrived example, but you get my point.

It's not a contrived example. I see it all the time in Java codebases, and it drives me mad. I always flag it in code reviews and demand an explanation: "what purpose does this comment serve? What would be unclear if we removed it?".

Re: Four kinds of documentation

#36

Post by harimau777 »

My experience has been that having names for things makes it easier to think and communicate about them; including in documentation.

For example, once I learned the term "tail" I no longer had to say "every element except for the first one".

As another example, learning about "complete" versus "partial" functions gave me the vocabulary to better understand and communicate about certain types of errors.

Does anyone know of any resources that describe different types of useful vocabulary such as this?

Re: Four kinds of documentation

#39

Post by TuringNYC »

JoeAltmaier wrote: post #13
remotedeveloper wrote: post #8

Earlier quoted context omitted.

I work with a very large, complicated piece of software which has quite a comprehensive API but it's basically CRUD on top of a database. There is zero documentation about what happens when you update an object - only OpenAPI. To find that out, you would have to dig in to the database triggers. Half of working with it is trial-and-error and the other half is hope-and-pray.

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.

Re: Four kinds of documentation

#40

Post by xtiansimon »

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've been trying to get my head around a particular Swagger project. Here is a funny email exchange from my request for documentation:

... Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me.

... The api documentation for [product] can be found here: https://api.[product].com/

... Sorry. That's not what I mean by "documentation". It's certainly non-linear. I don't know how to "read" this site to gain an understanding. It's kinda sparse:

   GET /v2/adjustments > Implementation Notes: Fetches a list of adjustments.

   GET /v2/reportCategories > Implementation Notes: Fetches a list of report categories.
... Hm, I think swagger documentation is pretty standard among APIs I've worked with before. I'm pretty sure it's all they have.

... "Swagger Documentation" is a special class of documentation for sure; Nobody likes writing documentation.

Talk about insider (them)/outsider (me).

Post reply on HN