|
I believe that there are two main reasons software engineers don’t write documentation. Tools play their part but they are a hugely distant third. Present company not included. (I hope)
|
|
|
|
|
Quote: Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly.
Isn't that also true for programming?
So if you can't write documentation because of the above....finish my sentence. 
|
|
|
|
|
In one sense, the need for critical examination and clarity is absolutely true for programming, because either the code works or it doesn't. However, code that works isn't always expressed clearly.
Writing is different in that there isn't as an objective measure of whether it "works" or not. You'd have to survey its intended audience to assess how well it works. Writing is also a different skill. Granted, technical writing isn't creative writing, but we don't expect writers to be good programmers. So technical writing is often done by specialists, which has the advantage of bringing in the perspective of someone who is more removed from the software.
|
|
|
|
|
So, write your documentation - actually your plan - before coding, and
Quote: focus on documenting the choices and why they were made
Oh sanctissimi Wilhelmus, Theodorus, et Fredericus!
|
|
|
|
|
Writing docs isn't just hard but is very, very, very boring. It's also very time consuming. Writing good docs (which includes things like diagrams and examples) takes longer than coding.
And, from a personal advancement perspective, it doesn't win publicity or mindshare.
I can see no simple, fundamental way round these issues.
modified 30-Apr-21 5:43am.
|
|
|
|
|
markrlondon wrote: Writing docs isn't just hard but is very, very, very boring.
I don't see that as a valid point; imagine doctors not keeping dossiers up to date because "it is boring". It is paid work, and doesn't have to be particularly interesting at all times.
markrlondon wrote: Writing good docs (which includes things like diagrams and examples)
We'd first need an example of "good docs"; lots of documentation that I encountered looked "fluffy"; too many words, some marketing sprinkled in there, more diagrams and screenshots than needed - and sometimes severely lacking an index.
Always enjoyed MSDN. It's to the point, concise and makes relevant parts easy to find. Perfect balance between being understandable and minimal.
markrlondon wrote: And, from a personal advancement perspective, it doesn't win publicity or mindshare.
The articles here prove otherwise on the publicity front. After all, an article is a form of documentation, even if it should be written in a different style from the technical documentation for a project. And that exists, not for mindshare, but to make it easier to understand the project and its parts, which in turn reduces maintenance costs.
Bastard Programmer from Hell 
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
markrlondon wrote: from a personal advancement perspective, it doesn't win publicity or mindshare.
That is a huge problem. It's just not recognized as "real" work by managers unless there's a customer willing to pay for it. 
TTFN - Kent
|
|
|
|
|
Kent Sharkey wrote: It's just not recognized as "real" work by managers unless there's a customer willing to pay for it.
Because they can't invoice it, but it should be part of the projects' cost anyway.
Good documentation saves a lot of money for large multiple-year projects; it's a waste if it is an internal tool that has a few lines of code. Managers call those "hidden costs", like rent.
Problem is not the documentation here. It is the quality of the manager.
Bastard Programmer from Hell
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
Disclosure: While I was in college I spent almost a year in a technical writer position. By the end, I no longer had any hesitation when it came to writing. In the 40 years since, I've written thousands of pages of all kinds of documentation, from formal specifications to user manuals and application help files.
I think this article and most of the responses thus far miss an essential and fundamental property of all writing: knowing who's your audience. You must answer the question: who are you writing this documentation for? As an example, documenting a library's API for use by other developers is very different from documenting that same library for maintenance developers working on the library itself. Both of these differ in turn from user documentation for an application that uses the library. All three cases could conceivably be written by the developer and all three documents are vastly different from each other.
Once you answer the 'audience' question correctly and completely, the kind of information that needs to be in the document should be pretty obvious. Often that will also tell you how the document should be organized, if the items of information should be presented in a particular way or order, and so on. At that point it's a matter of filling in the blanks. Yes, it can be time-consuming but it can also be useful. I've had many times when I've been writing documentation and discovered that the associated software needed a change, just from the different viewpoint when writing vs. coding.
I will freely admit my work experience has left me with little patience when it comes to engineers complaints about writing documentation. Many gripe that it's boring, tedious, or (my favorite) beneath their dignity to be asked to document their work. I've frequently been the brunt of their contempt when I insist on documenting something. In my view, if your code goes anywhere other than the computer directly in front of you, you damned well better be able to document it. Software is complicated and written documentation is often the default (can you imagine verbal documentation for Boost?). For anyone else using it, the perceived value of your code is limited by the documentation you provide.
Software Zen: delete this;
|
|
|
|
|
|
I do tend to preach at times
Software Zen: delete this;
|
|
|
|
|
Sometimes it is necessary to preach
|
|
|
|
|
.....by the time the bugs are fixed they hardly have any life...
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
Research firm Gartner estimates the market for hyperautomation-enabling technologies will reach $596 billion in 2022, up nearly 24% from the $481.6 billion in 2020. Acronyms deemed profitable
|
|
|
|
|
Kent Sharkey wrote: Acronyms deemed profitable
Almost the same as last year. But this year will be the year of the AI desktop!
Bastard Programmer from Hell
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
|
Continuing our series on the over 100 API changes in .NET 6, we look at extensions to the LINQ library. These are not the weakest LINQs. Goodbye
|
|
|
|
|
After spending $9 billion combined, Verizon may sell units for $4 billion or so. Have some spare cash? You could be a Yahoo!
I wonder if part of the price for AOL is the warehouse of CDs?
|
|
|
|
|
Kent Sharkey wrote: I wonder if part of the price for AOL is the warehouse of CDs?
LOL!
This explains why they've been so ruthlessly culling stuff like Yahoo Groups. The irony is that, even now, there was and is money to be made with mail lists (and web forum integration). It just needed some investment. It could have been a profit centre; but no, they killed it instead. No surprise they're not doing well.
|
|
|
|
|
And just before any potential sale, they'll have also killed off Yahoo Answers. Like with Groups it had fallen behind the competition due to neglect, but with some work it could become a viable competitor of Quora again.🤦♂️
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, weighing all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
|
|
|
|
|
A group of researchers from Tel Aviv University recently discovered how shockingly easy it is to identify a person based on a tiny sample of their musical listening preferences. Deep Down Trauma Hounds (Skinny Puppy); Escape Artist (Zoe Keating); Two Sisters (Clannad). Checks out.
|
|
|
|
|
The week-long tabletop exercise, now in its third day, aims to find out whether our current technologies, systems, and institutions could handle the crisis if an actual asteroid were to threaten Earth any time soon. Incoming!
|
|
|
|
|
Didn't 911 occur on the same day that a 911-style emergency management exercise was taking place?
And didn't the current pandemic begin just a month or so after an international modelling exercise of a very similar pandemic disease took place?
Just... you know... noticing. Synchronicity is really strange sometimes, isn't it.
And there do seem to have been a lot of reported fireballs/bolides recently, more than usual.
2021 is going to be a great year.
|
|
|
|
|
markrlondon wrote: And there do seem to have been a lot of reported fireballs/bolides recently, more than usual.
Where's Bruce Willis when we finally need him? 
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
Microsoft has announced that the Windows May 10th 2021 Update (21H1) is complete and being prepared for release. Incoming!
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
