Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why programmers don’t write documentation

kislayverma.com

Post reply on HN
Print view View original

121–130 of 153 posts

Re: Why programmers don’t write documentation

#121

Post by TeMPOraL »

ChuckNorris89 wrote: post #80
pdimitar wrote: post #75

It's bloody hard, you say? Hm, maybe in part of the cases, but you know what else is even harder? Getting onboarded in a new project and having zero clue why X is written like that, why is Y is where it is and why Z is using a 10-year old thread-pool scheduler that is grossly inefficient. And you have to deliver feature A and bugfix B and you might collapse the house of cards and of course, critically important piece…

> critically important pieces of institutional knowledge are missing And the guys who have it are the "10x devs" in that joint. >Or they find it "boring". Or, it doesn't count much towards your annual performance review so then why bother if you have enough stuff on your plate that does count towards your performance review. When was the last time someone got promoted because they write really, really good internal d…

> Let's face it, most web facing SW nowadays is like fast-food. Investing tons of time in writing quality documentation would by like a triple Michelin star chef writing a 20 page article about a doner kebab.

A lot depends on the project size and expected lifetime (honest expected lifetime). But you can look at it from another perspective: the most basic internal documentation, like commit messages explaining why something was done, interface-level comments explaining what a function or class does, internal comments explaining the tricky bits of implementation - they all increase velocity of product development. So it's a good thing to do on team level.

(But it's kind of a "pay it forward" thing. You may not benefit much from your own comments, but you'll be thankful for the ones your co-workers leave.)

Re: Why programmers don’t write documentation

#122

Post by _y5hn »

seiferteric wrote: post #68
kordlessagain wrote: post #56

I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.

I think the answer is just to have more people in the loop. Why do I have to write code, tests, documentation, dealing with jira tickets etc... In the old days, people had secretaries to handle some tasks. I would gladly exchange lower pay for having more people to spread out these tasks.

If it was that easy, there would indeed be a silver bullet: Secretaries could write specs that would compile into magical code solving every problem. They'd also infer user tutorials and data flow diagrams from machine code, to help out fresh blood.

What people can do it help allievate the gaps, but sadly, they're not geeting much help from managers and business people this time 'round either.

Re: Why programmers don’t write documentation

#123

Post by TeMPOraL »

MereInterest wrote: post #48
dasil003 wrote: post #43

There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim…

I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way. * Can be learned from the code: Function A accepts a C-style pointer to a data array. * Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doin…

* Cannot be known from the code: The intent to use the array as persistent storage in the future is driven by the ongoing work around feature F.

* Cannot be known from the code: Feature F morphed into feature Q, and the function A doesn't really need that array anymore. Since nobody could tell why it was there in the first place, nobody removed it afterwards.

The next time someone has to make changes to function A, they'll be thankful for a comment or commit message that explains the first point above - as it'll let them complete the picture and realize it's no longer needed, so they don't have to worry whether their change is impacting anything else in the program through (mis)use of that array, but they can instead just go ahead and delete it.

Re: Why programmers don’t write documentation

#124

Post by 29athrowaway »

maya24 wrote: post #69
29athrowaway wrote: post #20

Hire a technical writer. Not only for your external documentation... for all of it. If you are afraid of the costs, do the math. 1 technical writer for every 20 developers.

This is a terrible solution. Writing is part of the developers job requirements. And writing doesn't just happen in documentation. It happens in emails, technical specs, presentations, code comments. Developers should maybe just get better at their job because documenting and writing is part of it.

Writing is part of developer job requirements, sure.

Is technical writing part of your interviews? do you hire, promote or fire people based on technical writing performance? Is documentation taken as seriously as other code deliverables?

Why paying an expensive senior developer to maintain documentation in a non-commited way when you can pay a technical writer to do it better and for cheaper than the engineer can? And with real ownership and accountability over documentation, unlike the engineers.

Technical writers are cost efficient and pay themselves very quickly.

Re: Why programmers don’t write documentation

#125

Post by 29athrowaway »

zabzonk wrote: post #42
29athrowaway wrote: post #20

Hire a technical writer. Not only for your external documentation... for all of it. If you are afraid of the costs, do the math. 1 technical writer for every 20 developers.

Now you have one more problem (several, in fact) - explaining the business and the software to the technical writer. This is so difficult, that in all my long career in software development and management, I never saw any company specifically hire a technical writer, though I have done a lot of technical writing myself, on the side.

The technical writer can be involved in the release management and ask for details that then he can use as a starting point.

They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them.

Then, while many developers write excellent documentation... some other developers truly SUCK at documenting. Some people like to sound intelligent and their comments read like a choose-your-adventure monologue that cannot be read linearly. Or they use vague, ambiguous language, or overuse acronyms or abbreviations. Or they sign every piece of code they touch like a dog scent marking your entire code base. Or they use profanity, or they get offtopic or humorous... All of that is a distraction from doing my job.

The technical writer takes care of those problems for you. They can create guidelines for documentation so that people treat documentation with the respect it deserves.

Re: Why programmers don’t write documentation

#126

Post by eaa »

First of all, if there is no documentation then it's not engineering.

If you don't agree, then imagine civil engineers which don't bother writing documentation, or mechanical engineers not bothering to do blueprints, or electrical engineers don't bothering to document schemata, properties and behaviour of components, etc. Would it be a work of an engineer?

The biggest problem with SW documentation is that people don't know how to do it properly and even why to do it at all. Mostly because people in universities also don't know how to do it properly and so it is not taught. As a result the documents are often a mix of useless prose with some incomplete and imprecise diagrams. That's why most people don't bother.

David Parnas makes it clear WHY and HOW to write documentation for SW.

If you wonder how good can documentation be then google "requirements document for A-7E aircraft". Barry Boehm has said that it's the best requirements document he has ever seen. I guess that it's still the best one!

Re: Why programmers don’t write documentation

#127

Post by tunesmith »

As a backend programmer, I really thought I had this nailed. I'm good at writing clean, mostly-pure code that composes well. The idea is to get the code to the point where the "what" and the "how" is communicated (clearly; avoid cleverness whenever possible) by the code itself, and to save the comments for the "why". That way if the "why" gets out of date, you can revisit whether that code should be there at all. The exceptions should be the highly tuned code that is hard to read - documenting what/how is more appropriate there, and that code should rarely change anyway.

But all that started changing with react hooks on the frontend. With contexts and state going everywhere, it's really hard to document. How do you document a state machine that by definition is spread between multiple code locations? You can document a hook's purpose but it doesn't tell you anything about complex behavior. It starts to feel as hard as documenting code that has a bunch of mutable global variables.

Re: Why programmers don’t write documentation

#129

Post by mssundaram »

yoz wrote: post #97

There are a remarkable number of commenters saying no , documentation isn't hard actually . One question for those commenters: How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months? If you're not testing it, then how can you consider it done? Would you do the same with y…

I like your version of Foo and Bar - Fribblers and Borgles

Re: Why programmers don’t write documentation

#130

Post by eaa »

yoz wrote: post #97

There are a remarkable number of commenters saying no , documentation isn't hard actually . One question for those commenters: How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months? If you're not testing it, then how can you consider it done? Would you do the same with y…

Maybe make someone actually use it during the project?
Post reply on HN