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

171–180 of 203 posts

Re: Four kinds of documentation

#171

Post by marcosdumay »

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.

That comment says the code author actively stopped to think about the function and didn't find anything worth noticing about it.

It is a completely different situation from the lack of such a comment, that implies that the author didn't stop to consider the function, and you can find any kind of strange things when calling it.

Re: Four kinds of documentation

#172

Post by dllthomas »

dragonwriter wrote: post #167
the_af wrote: post #34

Earlier quoted context omitted.

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

Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes. Sure, if documentation is treated as an afterthought it tends to reflect that attitude.

In my experience, once you've got a bit of documentation, finding everything relevant to an intended change can be non-trivial and error-prone even if it's done first.

For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.

Re: Four kinds of documentation

#173

Post by joshmarlow »

steveklabnik wrote: post #68
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…

With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!

I'm going to hijack this thread to recommend Rust Skeptic - https://github.com/budziq/rust-skeptic

It checks for rust snippets in markdown files and attempts to build them when you run `cargo test`. It helps keep docs and code in sync.

Re: Four kinds of documentation

#174

Post by the_af »

dllthomas wrote: post #172
dragonwriter wrote: post #167

Earlier quoted context omitted.

Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes. Sure, if documentation is treated as an afterthought it tends to reflect that attitude.

In my experience, once you've got a bit of documentation, finding everything relevant to an intended change can be non-trivial and error-prone even if it's done first. For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.

Plus you cannot really automate checks for documentation up-to-dateness.

I mean, with actual code you get some help from the tools. No silver bullet, but at least you have type checks, compiler errors, something. But with docs there's no way to automate checks to see if the doc is still relevant and accurate. And what terrible tools are there tend to lead to "boilerplate docs", like those javadocs mentioned in a comment elsewhere.

Re: Four kinds of documentation

#175

Post by ldng »

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…

That is not really docmentation. That's Github Geek Marketing. And sadly nowadays most thing published on Github stop there.

Re: Four kinds of documentation

#176

Post by zomglings »

jpincheira wrote: post #94
zomglings wrote: post #88

Earlier quoted context omitted.

Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia. As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :) Thank you for posting the podcast.

Seems we're both in the same boat! Exactly. If on live demos, they go like "wow, didn't know this case". That's exactly what you should go write after. I have a huge list of things to write about. Hope you enjoy the podcast, there are some gems there about SEO. Ruben Gamez —the person in the podcast— was also technical and learned his way around SEO. Mind sharing what your product is?

Very happy to share - my co-founder and I started a company called Simiotics, where we offer metadata stores for data, preprocessing functions/transforms, machine learning models, and statistics. We also have tools that integrate with these metadata stores to automate work that most data science teams perform manually today - running preprocessing jobs, updating models in production, monitoring the distribution of data and predictions in production models, things like that.

Our pitch is that, instead of having to do complicated things like set up an Airflow cluster, spin up a Kubernetes cluster and build helm charts, manage Spark, etc., a data scientist can just call out to our APIs from their Python programs (which may be running in notebooks), and we take care of the stuff they need to do but don't want to do.

This is our website: http://simiotics.com

These are our docs: http://docs.simiotics.com (They are in a very sorry state, and it embarrasses us to post them here, but we are going to use that embarrassment to push us to make them better!)

Re: Four kinds of documentation

#177

Post by closed »

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…

nbsphinx is super handy! A cool tool to combine with it is jupytext, so you can keep your notebooks as rmarkdown files, which is a bit more human readable / GitHub editable.

I did this with a recent library, siuba, and have not regretted it!

https://github.com/machow/siuba/tree/master/docs

Re: Four kinds of documentation

#178

Post by dllthomas »

the_af wrote: post #174
dllthomas wrote: post #172

Earlier quoted context omitted.

In my experience, once you've got a bit of documentation, finding everything relevant to an intended change can be non-trivial and error-prone even if it's done first. For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.

Plus you cannot really automate checks for documentation up-to-dateness. I mean, with actual code you get some help from the tools. No silver bullet, but at least you have type checks, compiler errors, something . But with docs there's no way to automate checks to see if the doc is still relevant and accurate. And what terrible tools are there tend to lead to "boilerplate docs", like those javadocs mentioned in a com…

I mean, where it's applicable doctest is amazing. But that's not everywhere.

I've been wanting some kind of system to add references to tests to documentation, in the spirit of citation. Maybe I will build it at some point.

Re: Four kinds of documentation

#179

Post by ergothus »

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.

Interesting, because when I switched to Java I absolutely hated (and still do!) the autogenerated documentation. Included was every variation of the constructor. Missing was HOW I would actually call it, and where I would get the params to it.

It's been the better part of a decade, so I can't actually quote correct APIs, but I recall trying to connect to an LDAP server - I just needed to call one of four constructor methods, which seemed to imply I needed an LDAPContext object. Looking at that object told me the 10 bajillion values it had, but no idea how to set them.

Once I saw an _Example_, which IIRC was basically calling a method to clone the default context object and setting the one or two params (such as server url), I could then pass that to one of the constructors I saw the docs for.

The generated documentation was 100% _correct_, but not _useful_.

Other languages I had been in had very example-focused documentation, and were far more accessible and usable as a result, even with occasional challenges where the docs might slip behind - that almost always tended to be corner cases, while the Java approach made the most common need into a corner case.

Re: Four kinds of documentation

#180

Post by GordonS »

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 find auto-generated documentation useful for libraries, and for powering intellisence kind of docs for libraries - it's pretty useless for anything other than libraries/APIs.

Unfortunately, in my experience a lot of devs turn on auto docs in their project's settings and call it a day, especially if it's not a library/API!

Post reply on HN