Why programmers don’t write documentation
-
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)
-
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. :laugh:
Latest Articles:
Client-Side Type-Based Publisher/Subscriber, Exploring Synchronous, "Event-ed", and Worker Thread Subscriptions -
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. :laugh:
Latest Articles:
Client-Side Type-Based Publisher/Subscriber, Exploring Synchronous, "Event-ed", and Worker Thread SubscriptionsIn 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.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
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)
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!
-
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)
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.
-
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.
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 :suss: "If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
-
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.
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. :sigh:
TTFN - Kent
-
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. :sigh:
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. :sigh:
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 :suss: "If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
-
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)
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; -
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 :sigh:
Software Zen:
delete this; -
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)
-
I do tend to preach at times :sigh:
Software Zen:
delete this;
