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

21–30 of 203 posts

Re: Four kinds of documentation

#21

Post by laumars »

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 APIs that really should have been documented but weren't) and some of the example code Microsoft did publish was next to useless.

There was one occasion when I was teaching myself DDE (anyone else remember that?) and the example looked a bit weird because the example application would launch and call itself. "ok," I thought, "I'm obviously missing some logic when reading through. Maybe I should just run it to test it's behaviour." Five minutes later I was forced to reboot after my suspicions were confirmed -- their official DDE example was literally just a fork bomb. Well done Microsoft /s

However I did learn a valuable lesson that day: never trust example code.

Re: Four kinds of documentation

#22

Post by undergrowth54 »

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…

> 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'm a bit of an extreme case, but Many engineers feel so incredibly uncomfortable with writing prose that they avoid it. Why? The standard of writing education for STEM-minded people is low. Why? Writing education in high school is focused on literary analysis essays rather than on learning to describe facts and systems with vibrant clarity.

[1] https://getputpost.co/overhauling-api-docs-with-gocardless-9... ---

Anecdote: At age 14, my school had poster which listed the professions one could use mathematics in. Someone pitched us on how much need there was for people who could program. Shop classes and science classes had assignments which were miniature versions of problems we could see in the real world. Nobody did this for literary analysis. I didn't know how to ask "why are we doing this?" other than as a snotty teenager saying "Hey english teacher! Justify why your life's work has meaning." In reality, I wanted to say "I'm having trouble getting oriented around this subject. I'm having trouble understanding what it means to make progress or make something good. Can you help me?"

I searched for writing advice devoured works like Politics and the English Language and Strunk and White. But they just helped me get better at editing, not at putting thoughts onto a blank page.

Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring." At age 17, I didn't have the self-confidence to persist to find a different teacher who would be interested in that.

Anecdote: At age 20, in an engineering university, I knew that I struggled with getting the first draft of an essay done. I went to the writing center at my school. But I never built a good workflow with them for how to get the first-draft-writing process. I didn't know how to learn to write without an anxiety so strong that I felt compelled to dig my nails into my skin. I didn't know how to ask professors or TAs for help. I accepted that writing was just staring at the paper until my eyes bled. I wasn't going to learn to write. I endured my required writing classes. hoped that once I graduated, I might be able to work in a way to

Anecdote: At age 29, I had to quit a visa-sponsoring software engineering job and very quickly find a new one, because of my failures with writing first drafts interacted with a business process for immigration-law compliance.

---

I've now found two coaches and plan to spend this Saturday working on a first draft of a blog post and trying some of their strategies. Wish me luck.

Re: Four kinds of documentation

#23

Post by acidburnNSA »

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 comments all over both the doc and the test that said YOU HAVE TO UPDATE THE OTHER IN SYNC!

[1] https://nbsphinx.readthedocs.io/

Re: Four kinds of documentation

#24

Post by michannne »

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…

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

Re: Four kinds of documentation

#25

Post by Karliss »

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.

There is also "@param p price". How about not giving argument single letter name so that you don't have to explain it in comment.

Re: Four kinds of documentation

#26

Post by harimau777 »

acidburnNSA wrote: post #20
protomikron wrote: post #14

Earlier quoted context omitted.

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.

Yeah, I was coming to say it can be done right, and that's your point too. If you spend the time to put what a thing does, why it does it, and how it does it, with meaningful hyperlinks to related things, then the auto-collected docs can be really slick. Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and wr…

It seems to me that the issue with auto-collected code is that, if done well, it captures the behavior of the code itself. However, it doesn't capture the specification of how the system should work (as opposed to just how it does work) or the higher level design and strategy of the system.

Re: Four kinds of documentation

#27

Post by arjenschat »

lallysingh wrote: post #9

Yes, this is critical stuff!! I've seen a lot of effort put into unguided documentation efforts that put out huge, unapproachable times that helped nobody.

Indeed. We have simple process to create maximum support impact with minimal effort in documentation.

With every support request we ask ourselves: Why is this person contacting us? Is there a simple ui change or wording to prevent confusion. Basecamp coined the term "wordsmithing" for this endless process of fine tuning. [1]

Only after we are happy with the amount of support request a feature generates, we document it.

Doing it this way has a couple benefits. You kind of create a long term user test. You can't spoil the user with knowledge from documentation. There is no way you can give hits to the user to perform a the task. With every support request you can multi variant test your explanation.

[1] https://signalvnoise.com/posts/3633-on-writing-interfaces-we... (2013)

Re: Four kinds of documentation

#28

Post by Consultant32452 »

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.

I've written MANY javadocs like this, and I agree they are useless. They are derived from draconian build processes that fail builds when there's not a javadoc present. So for trivial methods like setters and getters this is the kind of comment/javadoc you get from me.

Of course, the other side of this coin is that without these draconian build processes I probably wouldn't write the useful kinds of javadocs I write for significant methods.

Re: Four kinds of documentation

#29

Post by Waterluvian »

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?

Re: Four kinds of documentation

#30

Post by acidburnNSA »

harimau777 wrote: post #26
acidburnNSA wrote: post #20

Earlier quoted context omitted.

Yeah, I was coming to say it can be done right, and that's your point too. If you spend the time to put what a thing does, why it does it, and how it does it, with meaningful hyperlinks to related things, then the auto-collected docs can be really slick. Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and wr…

It seems to me that the issue with auto-collected code is that, if done well, it captures the behavior of the code itself. However, it doesn't capture the specification of how the system should work (as opposed to just how it does work) or the higher level design and strategy of the system.

I agree with that too. There needs to be a lot of pure narrative in addition to the auto-collected API Docs. My big project has User Guide (with intro, vision, tutorials and how-tos), Developer guide (with architecture description, requirements specs, implementation overview) and then auto-collected API docs with all the details of how it's currently implemented. In the "notes" admonitions throughout the API docs, there's a some historical information and description of why it is the way it is and how it should ideally be (as appropriate). This feel like it works pretty well. Then again, I wrote a lot of it so I'm biased.

There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.

Post reply on HN