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

41–50 of 203 posts

Re: Four kinds of documentation

#41

Post by undreren »

dtech wrote: post #33
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?

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.

You can add two new columns to your Kanban board called "Documentation" and "Documentation Review".

Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.

Re: Four kinds of documentation

#42

Post by noxToken »

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.

> No shit sherlock! I admit that this is a contrived example, but you get my point.

Not a contrived example. There are an absurd amount of libraries that do this and call it documentation. There will be a nice, tidy example of how to use the library with a toy example. That's fine. The intro probably doesn't need to go that deep. Then I move to the technical documentation or API, and that's what they have to offer.

Re: Four kinds of documentation

#43

Post by Already__Taken »

arjenschat wrote: post #15

What we've learned is that you can roll the how-to guides and tutorials into one. Once a users has learned how to use a service, they only need some inspiration on how to use it in different scenario's Van der Meij, H Wrote a nice article [1] about minimalism in documentation referring to the first how-to guide (First_Minimal_Manual) [2] on how to use smalltalk for an IBM Displaywriter System (1980). This guide is al…

As long as your tutorials aren't so basic as to be useless in practice you can roll them together sure.

Re: Four kinds of documentation

#44

Post by andorov »

harimau777 wrote: post #36

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

I think it is also useful to be aware of the specific terms your team might need and introduce words to those more abstract concepts. This frequently happens with naming specific code patterns or important classes in the code, but can also be for how the team operates in general. A DSL for how your team operates.

Re: Four kinds of documentation

#45

Post by mfer »

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…

If you want your project to get real uptake and usage it's important to have fantastic documentation. Autogenerated documentation does no provide this. It is good as supplemental rather than primary documentation.

Re: Four kinds of documentation

#46

Post by robotbikes »

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

I think free writing such as journaling can help one get better at writing first drafts. Its important to practice the skill of getting something written.

Re: Four kinds of documentation

#47

Post by arjenschat »

harimau777 wrote: post #36

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

Being THE term is the holy grail for consumer brands. You can only get huge when your brand is the synonym for a whole concept or industry. Like ColaCola, Uber, Facebook, Tweet etc etc. For example Mark's explanation of Facebook [1] or the Photocopier sketch [2]

Edit: fixed link order

[1] https://youtu.be/cUNX3azkZyk?t=135 (video)

[2] https://www.youtube.com/watch?v=PZbqAMEwtOE (video)

Re: Four kinds of documentation

#48

Post by soulnothing »

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?

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 doing swagger. To me it should be written, then consumed by the back-end service. Then generate front-end clients. Anything less will result in bugs.

I've seen companies pile on so many services. To double check code generated swagger. Hit a bug, then have to maintain the swagger spec outside and not enforce it.

Re: Four kinds of documentation

#49

Post by protomikron »

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.

> 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 documentation, keep it up to date and take it seriously. I would argue, if you have auto-documentation you are more likely to miss that, because you have some kind of documentation somehow - irregardless if it's actually useful.

Re: Four kinds of documentation

#50

Post by xtiansimon »

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.

I really like writing the first draft of documentation. I get to run through the endpoints and even fine tune some of the details to fit to the big idea I'm creating about what the software does and how to use it best.

The problem comes months later when I'm in the weeds and a colleague asks a question. I try to fob them off to the documentation, but some details are out of date. I pray it's just one detail, and that I don't have to stop what I'm doing to rewrite the documentation now.

Post reply on HN