Why do software engineers hate writing documentation?I ask because I quite enjoy it! I'm talking about design documentation and implementation notes (NOT user manuals), which are non-existent in most of the codebases I've been handed. I can understand why a developer wouldn't want to write requirements (that's the analyst's job) or the user documentation (that's a technical writer's job) but I don't get why developers hate writing design docs.
I don't think I would feel as if I'd finished the job if I only wrote the code and walked away -- mainly because when I've been introduced to code-only situations I've seen how hard it is to figure out what's been done and what the software does. I would hate for people to suffer the same situation when inheriting my code.
What makes you loath writing supporting documentation for your code?
When I'm writing code, I am enjoying (sometimes) the process of solving a problem. Coming up with a solution is the "thrill" of programming, whereas writing documentation is just a laborious task I must do after the fact.
Bottom line: The act of solving a problem is more exciting than writing about how I did it.
Because we are lazy.
Because the minute you write a doc it is out of date.
Because it's boring. Instead of producing new code, new functionality etc., we "waste" time with old stuff.
I am a developer because I see myself as a builder, an engineer, a scientist. I want to build new bridges, not paint old ones red. I want to build more software to help more people. Documentation writing just feels like stagnation.
That does not mean it's not important to me, but spending 3 days on documentation means 3 days not writing new code.
I used to hate writing design documentation. The main reasons I hated it have already been touched on in some of the answers here:
But that has all changed. I don't love writing design documentation now, but I do it, and it doesn't make me feel like I'm pounding my head against a wall. What changed? Two things:
First, I worked on projects where I had to explain my software design to other people. Other developers had to interoperate with my code, or extend it, or maintain it. I learned very quickly that while I write very clean, readable, self-documenting code, once the scale of a project grows past a certain point, people are going to need more than a program listing to get started working with it.
The other thing that changed is that I got a lot of experience working with other developers' designs that were underdocumented. I would get through a week of research and prototyping, and at the end of that time find myself with a level of understanding that I could have picked up by reading a two-page document, had it existed. I came to resent developers who think so little of my time that they wouldn't spend any of their own to mitigate the problem.
So, here's my advice on writing design documentation productively and usefully:
I think the most discouraging thing about writing design documentation is that it is typically out of date very shortly after it is written. Frequently, this can make the effort to write design documentation feel like wasted time.
There are quite a few academic studies on this topic.
The main reason comes down to cost-benefit: any artifact of documentation may help someone else in the future (but it may not). Any artifact of code (unless useless) would in some form help the product in the future (and thus you). People generally prefer to plow forwards rather than stabilize what already exists. That's why everyone writes new code instead of maintaining it.
A second reason is that developers are not necessarily good technical writers. Writing well takes effort and thinking. So we end up writing extremely long text sections with very little in them.
As for inline code, much of its documentation is redundant and falls out of sync.
Finally (from my studies of API documentation), most material merely confirms expectations or elaborate details (e.g., look at the JavaDocs for Random), leaving the writer too exhausted to capture the critical and nontrivial directives.
Possible reasons:
Company-imposed conventions for design documentation, when those conventions are inappropriate for the project in question.
For example, requiring you to document your code's classes when your code uses data flow architecture or functional design style and is not object oriented at all.
Computer science and software engineering students are not taught to write well, so for them writing is painful and is to be avoided.
Management pressure to churn as much code as possible, at expense of design, unit testing, reviews and ahem design documentation.
If whatever you're creating requires people to read a lot of documentation, it's probably going to fail.
That's why I, personally, can't get excited about "writing documentation".
Why not create software and products that don't require documentation? At least for typical / standard uses?
1) Ridiculous expectations on formatting, layout, and content imposed by people I call the "PMI Crowd". In large organizations, Project Managers often expect long bullet lists of requirements and capabilities which are often less than useless when it comes to actually getting something done.
2) Nobody reads the F'ing M. When developers feel that they're writing something that nobody will read, they get discouraged and think it's a waste of time.
3) The pain of editing and collaborating in Microsoft Word. Nothing turns me into a semi-homicidal maniac faster than trying to contribute to a document where someone is unaware of how to use styles in MS Word. I often find myself spending more time on getting my documents formatted than filled with content in these scenarios. And god help me if the template to which I'm expected to conform is malformed.
probably for the same reason that some carpenters hate sweeping up when they're finished
going against the concensus here;
**Good Programmers/Developers/Software Engineers do write good documentation that you can always use to recreate whatever application it describes.**
Don't believe me?
Tell it to Brian W. Kernighan and Dennis M. Ritchie.
They wrote this little bit of documentation decades ago: C Programming Language
and only had to write a second edition in 1988
[1] http://rads.stackoverflow.com/amzn/click/0131103628Something you could try is providing good and almost fun tools for keeping track of the documentation within Eclipse.
One example is Doqua [1], a documentation Eclipse plugin for developers.
[1] http://www.inetsoftware.de/other-products/doquaThe question always reminds me of Süßkinds "Perfume": when Grenouille created a new scent, he considered writing down the formula a pointless detour, only to please his master. We are Grenouille (maybe you are not).
The most influential reason may well be that they aren't good at writing prose. Someone (cough) recommended to send developers to a weekends creative writing course - an interesting idea at least.
Second, the ship date. Before it's always race, and after everyone would like (you) to start something new.
Further, it feels redundant. The information is right there, in the source, more precise and more detailed than any other notation. Also, there is no immediate, tangible value.
Sometimes, a (subconcious) feeling for job security may play a role: they'll need me to keep this running, why should I help someone else to take the job away from me.
(Good programmers know that high maintainability is their ticket for new, exciting stuff, and that kind of job security means being chained to an ultimately sinking ship.)
Because it's boring.
Nobody is going to read it.
A well designed code base is its own documentation. Future maintainers are as likely to read your documentation as the end user is to read the User Manual, which is to say, they will not.
Because documents don't compile :)
Most of devs find coding fun. Writing docs is not fun in most of the cases. Anyway, we like it or not, we often have to write some.
I always thought it was because most of them can't write anything other than code fluently...
Because we know no one is ever going to look at it again.
I personally subscribe to the theory that "the code is the documentation". Why would I look at a design doc when I have the code? Design docs never tell the whole story, but the code does by definition. Design docs also aren't maintained well over time, so they might be wrong.
Design documentation:
Software architecture and implementation is evolving all the time especially when using agile methods to develop software. It's useless to copy software design in documents in addition to code. Instead the naming and architecture should be kept so clear that it shouldn't need documentation to explain it. And if you can't understand the code, what would be the point you would get from knowing anything about the design? Although in very large scale software projects having very high-level architecture document may save some time.
So basically software engineers hate writing documentation because it usually has no real value and it's required by some bureacratic convention.
My problem with taking all the time to write documentation (though when necessary I do it anyway obviously) is that it adds a second layer of things that need updating as things change due to circumstance. If you don't update the doc to maintain consistency with the living system, what good is it? Unless you do Literate Coding where your comments become the doc of course... then it's at least all together inside your source code.
I don't hate to write documentation, in fact I like to because I gain clarity and speed to develop a system, all the times that I wrote a specification I better understood the problem and clarified the design issues and basically everything.
Maybe I like to write also because that is the way I can remember everything, sometimes I'm programming several different things and personally I don't see any other way to do it. I admire how people remember all details of a system or chunks of code, but I don't think they remember it eternally, eventually they forget most of all those codes.
The documentation for me as I stated before is very useful, I feel I gain speed, clarity, a more bug-free code, better understanding of requirements, better comunication with my clients.
At the beginnig can be feel awful but the gains worth it, try it, you'll see.
I would say it boils down to a few reasons, inherent in how the minds of programmers work.
In my experience, technical design documentation is difficult, annoying and boring to write, and worth its weight in gold when you come back to maintain systems a year after the fact, or when you have to hand it to another programmer. So I write it. I don't like writing it, but I do it as a service to myself and my co-workers.
Documentation done properly is written BEFORE you write the code. Requirements doc are how you and your users know that you are done and that you built what was asked for. Design doc forces you to think the problem all the way thru before the system is in concrete. Documentation after the fact is boring and much more work than documentation written during development. 15 minutes of doc a day during development is a good habit to get into and much less painful than spending days after the fact. Documentation should be part of the creative programming process.
Designing and writing software is like cooking and enjoying the meal.
Writing documentation is like washing the dishes.
I've only realized recently that I am one of those annoying people who does not document consistently. I had originally skipped this step because, "I was in a rush". My job requires me to perpetually extinguish fires, many of them created by others, and I thought that "If I put all my time into coding, eventually I can go back... I just need to get this done right now." I've abandoned that philosophy for a couple of reasons.
First, I find that as I document, I have a much clearer idea what the functions are supposed to do and this often makes the code much more intuitive in the end. Ironically, writing documentation makes the code more self-documenting.
Second, by the very act of documenting, I know my own code even better and therefore can keep more of it in my head at the same time. When trying to keep track of dozens of functions, and potentially hundreds of objects, anything which can serve as a memory aid is useful. Thus, my speed actually increases when debugging.
Finally (and far from least), if I document, I can relegate the work to the people who would otherwise be unable to help fix stupid problems. More importantly, their questions on projects which were done months or years ago will be answered by documentation, and not by the ambiguous medium of, "oral tradition".
As an example - there is a project which I worked on briefly after the original programmer quit. He did not document (at all), and I unfortunately followed suit. Now, I find that the person who has taken over this project (as I was taken to act as a fireman again) needs to ask me quite a few questions on how things work. What was originally done to save time has now hurt me severely.
For me...
There is little glory in writing an implementation guide to your funky code, but much glory in writing cool code that solve a problem and makes someone’s job easier.
It’s a bit like the difference between building a bridge or painting the give way sign before it.
PK :-P
Because we are Artists, not Engineers.
A beautifully-crafted program is a work of art (although I've seen, and written, some dustbin lids in my time...)
In many places I have seen, documentation is mostly done for process reasons. Haven't seen anybody reading it after that. It gets quickly out of date too.
I think one of the main reasons is that how we are educated and trained. We were hardly taught, in most cases, in universities to document what we do. We were hardly ever told that this is important. We were hardly ever taught a course geared towards documentation. Thus the mindset that this is something 'extra' or 'over and above' what we do.
When we join our first company, the culture that we find is hardly different. However, there we have official "ISO" guys who force the generation of documents with emphasis on presentation than on content. This pushes us away from it even further.
This is always an interesting question to ask.
I think many developers are bred at an early age to think "code first, design second". Not saying that is a bad thing either. Just offering up an explaination. It's also funner to start coding and building something, rather than designing it.
To me, that is the core different between software engineers and coders/developers. You are a software engineer because you are comfortable with seeing and designing the problem at a level of abstraction higher than the source code. Documenting that design is a mechanical effort that deals with expressing your solution and its design in some way that is consumable by stakeholders, developers, manager etc. etc.
So, to answer your question, maybe the people you are asking to document their designs, or gasp!!, do some software design upfront, aren't necessarily software engineers, but pure developers/coders!
Good programmers are always on the lookout for programming the cool. Its strangest since, every other engineering discipline stresses on documentation. We programmers have to realize that we wouldn't have had softwares like gcc, mysql etc if the programmers wouldn't have documented properly. Here are some of my thoughts on the same State of Open source and its documentation [1]
[1] http://riteshnayak.com/blog/2008/07/31/open-source-sucks-and-why/It's an interesting one. I love writing UML diagrams / schema diagrams because it quickly represents the core relationships that you need to understand to get to grips with the system. If there's basic detail there, and there's comments and test cases in the code then it's normally pretty easy to understand what's going on. It'a also quite satisfying to tell them to read the document, and then come back! Also, there's an element of professionalism: how incompetant do you look if you have to explain to a new joiner that you didn't write any documentation?
I'm trying to encourgage my team to use wiki's more. If you have to ask something or you have to take time understanding something that you see as complex, then I suggest that they summarise what they've learnt and comment on any pitfalls they might have seen. I find it odd that people don't want to do it, even though it would have saved them time. I wonder whether it's:
I like writing documentation in some cases. For example documenting something that another developer is definitely going to use (hence my work will make their life easier).
Doing documentation becomes a really nasty chore when, say, a ladder-climbing manager wants you to be kinda vague and half-lie in the documentation just to further the manager's own agenda (instead of helping another developer).
Writing documentation can be a great learning experience imo. It's an opportunity to reflect on design decisions, what worked well, what can be improved etc.
One key point I keep in mind is that bad code with good documentation is infinitely better that good code with bad documentation.
If you have ever worked with MFC you will know what I mean. It was a strange code base to work from but there was documentation everywhere. MSDN, books, articles. This was all before the net really took off. With all that documentation it worked well.
There are many examples of code whose quality is debatable but has good documentation. There is even more examples of good code with poor or nonexistent documentation that is all but useless.
Writing decent, understandable code is much better than writing a doc about it. Usually things change and nobody bothers to update the doc. So it's usually outdated and catching dust...
Writing good code documentation and writing good software involve overlapping but distinct skill sets; you certainly have to understand the code to document it, but the fact that you wrote it doesn't necessarily mean you can document it adequately. Many developers / "software engineers", including myself, suffer from a blind spot in this area; having written / designed something, we no longer understand what it looks like to someone who doesn't already understand it. We can answer questions about it, and help someone on an individual basis to understand it, but writing documentation suitable for general consumption is hard, because we don't know which aspects are important, and which are self-evident. Thus we either end up writing no documentation at all, or writing documentation that goes into painful detail about trivial obvious aspects, while glossing over more important aspects, because we just can't tell the difference.
I personaly hate the tools used for documentation. Word, etc. Anybody knows of a markup language that is easy to learn, that will allow me to create UML diagrams, so I can do all my work from emacs and write the documentation at the same time I write my code? Export to PDF and possibly MS Word would be a huge benefit also. Organizing this documents would be also so much easier because I could check it in together with the source code.
Not all software engineers hate writing documentation; most good ones will accept it's an important part of the process, and will often use tools and techniques such as generating documentation from source code or using Agile-like techniques to record design decisions.
Bottom line is (as summarised in an excellent quote I once heard from a friend), documentation is like sex; when it's good, it's very good, and when it's bad, it's better than nothing.
The rule by commite problem. I've recieved perfectly good documentation from other coders. Clear concise and easy to digest. Then managers and QA got a hold of it and the coder spent another 4 hours formatting and correcting grammar. A week after he "cleaned up" the document and we both consumed it, a managers manager got a hold of it and made us change it. Another 4 hours and it was approved. The contents that we cared about was unchanged and the code was exactly the same as it would have been had the document been kept between programmers. IN the end the document was not tied to the code and was lost in the document management system. This pissed us both off and wasted at least 1.5 coder days. There. That's the reason I hate it..
Let me preface this by saying I won awards for technical writing during my university career, so writing is not a problem. Believe it or not, I actually enjoy writing user manuals and customer oriented documentation. It does give me a sense of pride that I can explain complicated concepts to users and they can immediately get to using the products.
So why do I hate documentation? I don't. I just hate writing the documentation required in most places as it serves no purpose; other than to absolve other people of responsibility.
For example, I have often encountered product managers who know absolutely nothing about the product. So they write a functional spec that is utterly useless. Now, I am supposed to tailor my documentation to match up to a poor functional specification. This follows all the way down the line of course in a matrix fashion... it infects everything from the design document to the test documentation. If anything, the product managers SHOULD BE experts in their field. They should know more about the practical use of the product than the software engineers. This is a principal problem I believe.
Now in terms of documenting 'code' there are a few issues. 1. Code should be well written so it doesn't need in depth documentation 2. There must be design documents that describe the overall functionality of the system. However, here too, I don't see the point of duplicating information. I often see documentation where it looks like the API was just copied from the header file to the document. I tend to just refer the documentation to the header file itself. It keeps the documentation short and up to date.
I have a general rule. Any documentation written before coding might be useful. Documentation written after coding is generally useless. Making up flowcharts after already coding it is just a waste of time. Sometimes it is useful to document things after coding... if you're doing something tricky for example. However, the general rule applies... if you can code it without a design document, someone else should be able to read it without a design document :P
I think it comes down to the size of the potential audience. Documents just don't have reach that our code does. I thinking about programming as an art and at the end of the day, we want our art to be seen and appreciated.
I like writing documentation. I like knowing where everything is.
Anyone who doesn't is under the illusion that software development is about writing code. This isn't so. Writing the code is as much a part of software development as checking the tire pressure is a part of being a mechanic. It is important, but its completely overshadowed by everything else involved.
The thing that people forget is that source code is a design. By this I mean that what the computer runs is not source code, but compiled code. Designs are normally made by designers so that builders know how to build what they wanted. In the computer world the builder is the compiler and the designer is the programmer, so source code is filling the roll of the design.
Source code already is an abstraction of what the computer is actually going to do. Any abstractions it is possible to make are normally already baked into the source code languages we use. If you can find a way to make meaningful abstractions to put in a design document, aren't you just creating a higher level programming language?
A lot of attempts have been made to abstract out the interesting parts of the software into a design format, but I don't think I have seen one that worked well yet. UML is almost there, but often does not match the reality well enough. How exactly are you supposed to present C#'s gets and sets in UML?
For the above reasons I’m with Jeff Attwood in that if your source code is not clear enough to understand anyway, then you are better off making your source code better than trying to explain it in a word document.
Sometimes I don't even know how I solved a problem or can't remember it, so I know writing the documentation is going to be hard :)
I think it is because we don't want to do thing twice in another language.
All programmers are lazy, and we should be lazy. We want machines do what we don't want to do ourself.
The source code does describe what it is. Technical documents will describe the same thing again in another high level language -> English, UML, others and others others.
If our tools smart enough, it should translate source code and comments into documents.
I don't know about everyone else, but when I write code that is intended to be used by other programmers, I really like to write some documentation (nothing formal or rigorous, just a section about the basic idea and a section about how to use it, and possibly some notes).
However, if what I'm writing is not meant to be for other programmers' use, I don't find much motivation in writing about it, unless I'm 100% sure that there are others who will read it.
I don't want to write something that no one's going to read!
I would say the most important factors are Time and Tools. Tell me a tool which will auto complete my sentences :)
And yes, at the cost of repeating some answers here, we are lazy and it is invariably boring to write.
I think I must be unique as a programmer. Because I actually LIKE and ENJOY writing documentation after implementing the solution. It "feels good" to write down a memory dump of all the important facts still on the stack in your head. And it "feels good" to know that all these little intricate details won't just get lost. And that months or years later you can just re-read the documentation you wrote and it gets you up to speed much more quickly.
I setup Screwturn Wiki for our documentation on new projects a few weeks ago and it is great. It is so easy to write or update articles in the Wiki that it becomes "fun" to maintain it. And because the Wiki-style format makes your articles "look" visually pleasing on the eye it just makes it all the better.
I actually enjoy documentation. It is like writing the storyboard for a movie, where the actual coding is like the script-writing. Even if not as formal as it could be, some level of documentation does help to flesh out ideas, isolate problems before they become problems, and provide insight as to the full progression of the project.
The reason that I don't do it as much as I would like to is not because of me, though. There is never enough time, according to the powers that be. I often find myself filling my commute with documentation tasks that I otherwise would not be able to do on-hours.
Its just because i hate my manager and dont like documenting any thing and it doesnt add any value to me.Thats what i feel.
Because I'm not given time to write it. Because the people who come after me and enhance, modify or refactor my designs, don't also change the docs, making them obsolete very quickly. Because we use a version of MediaWiki with a severely brain-damaged search feature that ranks several irrelevant or ancient matches before the page whose title is my search term.
Am I happy about this? No. But what can you do when the dev cycle resembles rushing from emergency to emergency?
Simply because writing good documentation is about as difficult as writing code, or at least it seems to take just as long, but we're not paid for that sort of writing.
Same reason why they don't like writing tests :
Because documentation is not code.
Because they don't know what their program does. Pa-dum-Pump.
To me, writing documentations are like writing your code all over again.
There is no good reason, in any case. Usually the people are lazy, not just for that, but for everything. I think doc is a grateful task, because it is the chance to admire your own code. If the programmer writes a dirty code, he will not fell pleasure to write about it. If you have proud of your code, it's super natural write about it. It's something like a therapy for me. Write about a good code is like massaging my ego. --- If I write a dirty & quick code, yes, in this case I hate write documentation about it.
