Hacker News Reader

Comment by JoeAltmaier | Hacker News Reader

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 and argument types. Ridiculous.

View on HN

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

That's part of it. Plenty of working developers will also omit tests and documentation even without the feature-factory time pressure though. A lot of times, the need for technical documentation isn't even a blip on the TODO radar. If I had a dime for every README where the last change was "Initial commit" and the file only contained

# <PROJECT NAME> Service

This is the new service for <TASK>.

....I could buy a good README.

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.

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

> documentation is treated as an afterthought

Bingo.

Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.

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.

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.

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

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

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.

Yes, since my commute changed, I've been regularly freewriting on the train and it has been helpful.

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

I laughed and then I got sad

Good luck and, for what it's worth, that was a very well-written comment.

Writing comments doesn't feel like "writing" to me; It feels like talking.

I've actually written some pretty long comments on reddit. Yesterday, I talked with one of my coaches and put some thought into why:

1) I don't have any memories of feeling anxiousness from commenting on reddit. This is unsurprising since it has never been assigned to me by a teacher/parent. If I ever feel like "Its unclear why I would respond to this or what I would say to this", I just choose not to comment.

2) I have memories of writing a comment and other people upvoting it or telling me that it was helpful. I don't have this for essays. I driven by making people happy, so that is a meaningful reward.

3) Because of those positive memories, as I am writing, I can imagine that a sentence I am about to write is going to be helpful. That imagining is a bit of positive re-enforcement that I can chase, inherent to the task. It is like when I was a kid and I would do math homework and I would solve a problem and see that I'd solved it. It is one of the tricks of TDD.

So, my plan this Saturday is to seek out the things that could possibly be intrinsically rewarding about writing:

A) Look for interesting phrases that I can craft to clearly explain something.

B) When I start on a section, write a question that someone could ask on a reddit thread, which this section answers.

C) When I write a section, imagine myself saying this as an explanation in response to that question and imagine someone else expressing gratitude for that explanation.

D) To avoid procrastination, mentally rehearse the act of starting and getting into the task. Simulate the trigger-response-reward in my mind so I can build the neural pathway. The reward I imagine should not be tied to completion, but come from the "I've just gotten started" state.

One book that (unexpectedly) gave me good tips on 'how to write' was Zen and the art of motorcycle maintenance. At some point the main character, who's a teacher in rhetoric, finds out that no one of his students know how to write. They all learned through analysis how great author have written this or that way, but they don't know where to start. They don't know the great authors probably didn't consciously decide to say 'here I'll put a metaphor, now a simile, and here you go, ellipsis'... They probably started with something simple, badly expressed, and refined, polished, restarted, embellished, simplified... The bigger hurdle of his students seems to be 'the first draft', the initial idea, the first words. Not even a 'blank page' problem. He gives them exercises in pure description, simpler and simpler and most of his students can't even start the first words. The funny 'solution' is just to start and write... Something... (and I'm not doing the book justice here sorry... I really like it, not as a philosophy reference (I've read many negative critics on this), but how it mixes the pain of being a father or a kid, the pain of mental illness, the pain of feeling cleverer than your peers, and the pain of being a teacher, a writer and a friend. All wrapped in a beautiful and sad storyline, lots of beautiful American scenery, and some advice on motorcycle maintenance...).

Another (possible) factor driving this is service- and support-based business models.

Good documentation, enabling user self-support, eats both cost and revenue.

(To what extent this is a conscious strategey and not simply decades-of-experience-born cynicism, I'm not entirely sure.)

Reply on news.ycombinator.com