Most developers I have worked with in the corporate world refuse to put things in writing. I have found the people that cannot write also cannot plan or architect software, which is then predictive of the output quality, process, and speed of delivery. It seems this is a form of executive functioning that when absent limits approaches to known patterns and oral discussions.
Writing docs well: why should a software engineer care?
31–40 of 45 posts
Re: Writing docs well: why should a software engineer care?
#323 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language.
Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support?
I've made a nice living "translating" from Subject Matter Expert (A/C/E, SaaS, Wall St) into business language for RFPs. 9 times out of 10 a person can talk out a story to me just fine - meanwhile they've stalled writing anything for 3 days past the deadline so it's just making my life more difficult. It's obvious people hate writing in the business realm.
Why? Because once it's written down there's a paper trail and accountability. That scares people who want to use language in shady ways. Hence the phone call after your email to talk about what you just mentioned but not by using the Reply button. Sooooooo predictable....
Re: Writing docs well: why should a software engineer care?
#33What are some good tools to write and maintain documentation?
I can keep docs for myslef in almost any way;) but docs maintened by a team need something easy to use. Plus on-premise storage because of security and privacy..
Re: Writing docs well: why should a software engineer care?
#34Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…
TDD in theory sounds great. What I've seen is thousands and thousands of tests, inconsistently written by dozens of different developers over the years. Testing silly little trivial things that makes the CI pipeline 10+ minutes. A least if you have lots of obsolete difficult to read docs you can easily ignore them, tests however are particularly toxic as it makes refactoring and cleanup very difficult.
Re: Writing docs well: why should a software engineer care?
#35Earlier quoted context omitted.
And testing is nature's way of telling you how sloppy your code is, I suppose? (recursion intended)
Yeah, testing shows you that your code is sloppy, writing is even worse since there is no testing at all, even the worst code is better tested than the best text as long as the programmer ran it once.
> writing is even worse since there is no testing at all
Isn't it possible to get a beta reader? Just someone who will go through your writing and give you feedback?
If you are writing docs, a lot of the time you'll also have coworkers there with you, that you'll be able to float the docs to for a quick look, or maybe other people who are interested in your project, if doing open source, or even a friend.
It is a bit worse than automated testing, but surely better than nothing!
Also, there are apps or sites like this, that help you detect when you have run on sentences or complicated wording: https://hemingwayapp.com/
Those could sometimes be useful.
Re: Writing docs well: why should a software engineer care?
#36Do you want your ops team waking you up at all hours of the night? Keep on giving half-assed docs to them. What should be done is gates where your shit never goes live unless you have it fully documented.
Re: Writing docs well: why should a software engineer care?
#373 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language. Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support? I've made a nice livi…
> Why? Because once it's written down there's a paper trail and accountability.
This. It’s the hard part of getting people to commit to operational plans on the business side as well.
Re: Writing docs well: why should a software engineer care?
#38Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…
TDD in theory sounds great. What I've seen is thousands and thousands of tests, inconsistently written by dozens of different developers over the years. Testing silly little trivial things that makes the CI pipeline 10+ minutes. A least if you have lots of obsolete difficult to read docs you can easily ignore them, tests however are particularly toxic as it makes refactoring and cleanup very difficult.
> tests however are particularly toxic as it makes refactoring and cleanup very difficult.
Properly written tests check the interface contract, and thus are very friendly watchdog that will warn you as soon as you got out the right path.
Tests that check the implementation details, instead, are hardly ever justifiable.
Re: Writing docs well: why should a software engineer care?
#39Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…
>Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it.
Maybe FOSS, but there is plenty of corporate SaaS and desktop apps that have basically zero documentation and you are told to contact the "support team" if you can't figure something out.
Re: Writing docs well: why should a software engineer care?
#40Most developers I have worked with in the corporate world refuse to put things in writing. I have found the people that cannot write also cannot plan or architect software, which is then predictive of the output quality, process, and speed of delivery. It seems this is a form of executive functioning that when absent limits approaches to known patterns and oral discussions.
There's a saying in the physics world, that you don't understand something unless you can explain it to a barmaid. There's also a traditional belief that you really discover the gaps in your understanding when you try to teach it.
Programming languages are intended to be human readable, so it's not entirely surprising that if you can't explain something to humans, chances are you might not be explaining it very well to the computer either.