Four kinds of documentation • Hacker News Board

Re: Four kinds of documentation

#51

Post by AstralStorm » Fri, Oct 18, 2019, 1:44 PM UTC

acidburnNSA wrote: post #23

Python developers: you can now make teaching tutorials in Jupyter notebooks and have them get automatically executed during the documentation build process and converted into theme-matching HTML by Sphinx with an extension [1]. I fired it up the other day and it's really glorious for tutorials. They're guaranteed to be up to date when you build the docs. Before that, I had a unit test that ran the tutorial with comme…

Not just Python, Jupyter has plenty of backends. Including C++.

Word of warning though, you might be tempted to use the tutorial prototype style for an actual application. That doesn't work in general.

Re: Four kinds of documentation

#52

Post by ses1984 » Fri, Oct 18, 2019, 1:44 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…

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

Re: Four kinds of documentation

#53

Post by protomikron » Fri, Oct 18, 2019, 1:46 PM UTC

ses1984 wrote: post #52

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…

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?

Re: Four kinds of documentation

#54

Post by jrd259 » Fri, Oct 18, 2019, 2:02 PM UTC

Two more categories of documentation: FAQ and trouble-shooting guide. Maybe you could call online chat-bots "documentation" (for trouble shooting or how-to?) but I've never seen one that actually did any good.

Re: Four kinds of documentation

#55

Post by crdoconnor » Fri, Oct 18, 2019, 2:03 PM UTC

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

Also because it's hard work that reduces the employer's dependency on that developer.

Re: Four kinds of documentation

#56

Post by kazagistar » Fri, Oct 18, 2019, 2:06 PM UTC

protomikron wrote: post #53

ses1984 wrote: post #52

Earlier quoted context omitted.

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?

Mostly it collates all your endpoints more easily, generates clients for different languages, genearates an online documentation and test page that makes your service self describing, and can be published out to third parties that dont have access to your code.

Re: Four kinds of documentation

#57

Post by minxomat » Fri, Oct 18, 2019, 2:06 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…

For abstract descriptions of what the code does, sure. But for small things like documenting the purpose of arguments, an IDE should warn about changes that are not reflected in the doc comment (type or a new arg altogether). IntelliJ IDEs are pretty good at that.

Rust for example also warns about code included in the doc comments example section which is invalid.

Re: Four kinds of documentation

#58

Post by [deleted] » Fri, Oct 18, 2019, 2:09 PM UTC

protomikron wrote: post #53

ses1984 wrote: post #52

Earlier quoted context omitted.

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?

[deleted]

Re: Four kinds of documentation

#59

Post by lkschubert8 » Fri, Oct 18, 2019, 2:12 PM UTC

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 would argue that's even better than documentation that defines how the code should behave.

Re: Four kinds of documentation

#60

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

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 information because there are no problems that this thing actually solves…