Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

There seems to be an aversion to writing even the most basic documentation. Our project READMEs are relatively bare. There aren't even updated lists of dependencies in the docs.

Is there something I'm unaware of in the industry that makes programmers dislike writing documentation? I can type out paragraphs of docs if needed, so why are others so averse to it?

More importantly, how do I convince them that writing docs will save us time and frustration in the future?

share|improve this question
12  
Because we know what we're doing! Why should we take time out of the day to write down what we already know and will never forget!?!? Seriously though, I deal with this same thing on a daily basis working on a code base that started its design process 7 years ago and has been updated daily ever since by a team of anywhere from 4-7 engineers. Documentation is something we've always struggled with, but is a necessary evil. –  Ampt Jun 20 '13 at 17:25
54  
Because experience has proven that no-one reads the docs. –  user16764 Jun 20 '13 at 17:26
7  
From a business standpoint reams of documentation is costing the company money here and now, when you could instead be working on the next project to make money. That need to always be producing profit is the pressure you feel against "wasting time" writing documentation. Plus, no one ever reads the docs and instead reads the sources because only they are the ultimate authority. –  Patrick Hughes Jun 20 '13 at 17:32
13  
Keeping the docs in sync with the latest code can be "challenging", if you're writing at a higher level than Javadoc or equivalent. –  Dan Pichelman Jun 20 '13 at 17:32
12  
It is not fun... –  MichaelT Jun 20 '13 at 17:33
show 10 more comments

14 Answers

up vote 16 down vote accepted

I don't think it's helpful to speculate on the motivations of people who aren't adopting something you think is good practice or who are continuing to do something you see as bad practice. In this business, the people who fall into one or both of those categories will far outnumber the ones who you'll see eye-to-eye with, so stop making yourself crazy.

Instead, focus on the problem and possible resolutions.

1. Write Good Documentation Yourself

It may not be realistic to expect that everyone on your team will direct their efforts to the things you see as a problem. This is especially true if you're a relative newcomer to the team. I'd venture to guess that you are, because if you were a founding member of the team, it seems quite likely you'd have already resolved this issue early on.

Consider, instead, working toward the goal of writing good documentation yourself and getting people to use it. For example, if someone on my team asks me where the source code for Project A is or what special configuration Project A needs, I point them to the Project A wiki page.

If someone asks me how to write a new implementation of Factory F to customize a thing for Client C, I tell them it's on page 10 of the developer guide.

Most developers hate asking questions that could make them look like they can't just "read the code" even more than they hate reading documentation, so after enough replies of this nature, they will go to the docs first.

2. Prove the Value of Your Documentation

Make sure that you take every opportunity to point out where the documentation is proving its value (or would have, if used). Try to be subtle and avoid "I told you so," but it's perfectly legitimate to say things like

For future reference, the wiki page of this project has information about the branch of the core code that was created for ongoing support of release 2.1, so in future we can avoid having to do a full regression test if people who are maintaining released versions check the wiki before checking out the code.

or

I am so glad I wrote down the steps for doing Task T. I don't really care if no one else ever uses it--it's already saved me more time than what I spent writing it.

3. Get Management on Board

After a few incidents where having documentation is provably saving time/money, you'll probably notice a distinct "thaw" toward documentation. This is the time to press the point by starting to include documentation time in your estimates (though honestly I usually update/create docs while long processes are running, such as compiles or check-ins). Especially if this is a recent hire, it's possible this won't be questioned, but instead viewed as a new practice you're bringing in from a previous workplace (which it may well be).

Word of caution: Most bosses don't like to make people do anything, especially things not directly tied to a billable task, so don't expect this support to be in the form of a mandate. Instead, it's more likely to give you relatively free rein to write more docs.

4. Encourage Documentation When You See It

Maybe part of the reason people don't write docs as often as they should is they feel no one is reading it. So, when you see something you like, make sure to at least mention that you were glad it was available.

If your team does code reviews, this is a time where you can drop in a subtle word or two to encourage good comments.

Thank you for documenting the workaround for bug B in Framework G. I didn't know about that, and I don't think I could have understood what you were doing without that in there.

If you have someone on the team who's actually enthusiastic about documentation, it doesn't hurt to cultivate that person through going to lunch or coffee and making sure to offer a little validation to counteract the discouragement they may get from seeing the rest of the team doesn't value the documentation as much.

Beyond that, it's really not your problem unless you're in a lead or management position. You can lead a horse to water, but you can't make it drink. If it's not your horse, you might not be happy that it's thirsty, but all you can do is fill the trough.

share|improve this answer
    
+1 for Point #2, directly answering the OP's question that begins with "How do I convince...." –  Ray Toal Jun 21 '13 at 7:52
    
I like this answer, the other ones focused more on the "why" instead of the "how" –  omouse Jun 21 '13 at 21:29
    
@omouse - that's because for the majority of cases, writing documentation won't save you time and frustration in the future. They're rarely accurate, and people never read them even when they are. –  Telastyn Jun 23 '13 at 16:57
1  
SOLID principles usually don't save you time or result in a better design, either, because most people either don't fully understand them or don't really give a crap. By your logic, we shouldn't aspire to apply them, GRASP, or any other good practices. Remind me why you bother to participate in programmers again? –  Amy Blankenship Jun 23 '13 at 22:56
add comment

There are two main factors in my experience:

Deadlines

Most companies are so date driven that QA, tech debt, and actual design are cut just so the project manager doesn't look bad or to hit some absurd over-promised client deadline. In this environment where even functional quality is cut, then a long-term investment like documentation has little chance.

Change

A relatively new best practice for developers is to de-emphasize comments. The idea is that keeping information in two places (the code [including tests] and the comments around the code) leads to a lot of overhead in keeping them in sync for little benefit. "If your code is so hard to read that you need comments, wouldn't time be better spent cleaning up the code?"

I personally won't even look at comments any more. Code can't lie.

Documentation follows the same vein. With the widespread adoption of agile, people acknowledge that requirements change regularly. With the widespread use of refactoring, the organization of code will shift pretty substantially. Why spend the time documenting all of this stuff that's bound to change? Code and tests should do a good enough job doing that.

share|improve this answer
10  
+1 for "I personally won't even look at comments any more", I think this is common; when you grow to a certain comfort level with the code itself, you can read it quicker than the comments (and quicker still if the comments aren't in the way), and the code doesn't lie –  Jimmy Hoffa Jun 20 '13 at 17:42
38  
This misses the point of comments, which is to explain why. They don't need to be all over the place, and they don't need to be very long, but a well placed link to the business rules describing why the next 20 lines of really bizarre logic exist in its current state is way more convenient than trying to slog through version history to find the original reasoning. –  zzzzBov Jun 20 '13 at 20:55
6  
@zzzzBov - absolutely, that is the modern view of things. This has changed from previous viewpoints that encouraged more pervasive commenting. Likewise, documentation of what the code is doing has decreased to documentation that focuses on why it's doing it (design docs for example). –  Telastyn Jun 20 '13 at 20:58
8  
Code can lie. The customer may have wanted something, and it was coded to do something else. So if all you have now is the code, it is right? –  thursdaysgeek Jun 20 '13 at 22:27
6  
Code can lie... I have a 4,000 line method (hey, I didn't create it, I just own it now...) and I see a collection clearly named "productList" so for a new change I add a Product object to it. Great. Only it doesn't work, turns out some past developer was being "efficient" and reusing the List type variable as to avoid cluttering the 4,000 lines with too many variables, and in that scope it contains Customer objects... –  Kevin Rubin Jun 21 '13 at 12:24
show 11 more comments

There are a number of factors in play here:

  1. Well-written code is its own documentation. All other things being equal, it is better to write clearer code that speaks for itself, rather than more documentation. Do that, and you will need to modify less documentation when you change that code.

  2. Writing documentation is arguably a different skill than writing code. Some software developers are better at it than others. Some are much better at writing code than they are writing documentation.

  3. Documentation should only have to be written once, not twice (once in the source code, and again in the programmer's guide). That's why we have things like XML comments and documentation generators. Unfortunately, using such tools can be more tricky and cumbersome than just writing the documentation by hand, which is why you don't see those tools widely used.

  4. Good documentation is time consuming, and hard to do well. All other things being equal, there can be more value to writing new code than writing documentation for already-existing code.

  5. When the code changes, you also have to change the documentation. The less documentation there is, the less that has to be changed.

  6. Nobody reads the documentation anyway, so why bother?

share|improve this answer
2  
re #1, I don't think that's ever the case, but #4 is definitely true –  omouse Jun 20 '13 at 20:07
3  
@whatsisname: Not at all. Write clearer code that requires less documentation, and you will need to modify less documentation when you change that code. –  Robert Harvey Jun 20 '13 at 21:47
2  
@thursdaysgeek: What those bullets mean is that you shouldn't have to write the documentation twice: once for the code comments, and again for the help file/programmer reference. You certainly shouldn't have to rewrite it twice. Are you guys reading this thing? –  Robert Harvey Jun 20 '13 at 22:35
4  
#6... I think this is a common misconception. A lot of people read documentation thoroughly. –  Dynamic Jun 21 '13 at 2:38
3  
@tymek: You got your sign backwards. Folks, this isn't a tutorial about how to create documentation; it's a reckoning of why developers have a negative attitude towards it. –  Robert Harvey Jun 21 '13 at 4:17
show 6 more comments

Elephant in the room: Programmers are not (necessarily) writers. Nor are they necessarily amenable to fleshing out their implementations to technical writers. Second Elephant in the room: Technical writers are generally not able to flesh out details useful for future developers (even if the developers would deign to explain them to them).

A complex system can become near inscrutable over time without proper documentation. The code becomes less valuable inversely proportionally to its scrutablility [sic]. Resolved, management hires Software Engineer who can read code and coax details from developers, pays him at a developer rate and mandates him to document and to maintain documentation. This writer can read code and will know what questions to ask and will fill in details as necessary. Just like you have a QA department, you have an internal documentation department.

The code will become more valuable, as you can licence it to a 3rd party (because he can understand it), the code can be more easily audited and improved/re-factored, you will have better code reuse even to where you can easily factor out more lightweight versions of your software, and you will be able to introduce new developers more easily into the project, your support engineers will love working for you.

This will never happen.

share|improve this answer
1  
Not to mention that when trying to describe to existing code it becomes harder to give a good description when the code and functionality is so complex that no one knows what it does already, so any new changes have an impact that the new developer didn't know about... –  Kevin Rubin Jun 20 '13 at 18:21
1  
I'd suggest that "basic ability to communication his or her intentions with (limited) documentation" is a necessary programmer skill. A programmer doesn't have to be a poet, but if he or she can't document, I honestly don't want him on my team. Such a person is a long-term liability. –  Jon of All Trades Jun 20 '13 at 23:16
add comment

More importantly, how do I convince them that writing docs will save us time and frustration in the future?

Does it do that?

There are two types of documentation:

Useful documentation

Documents how to use a finished product, an API, what IP adresses or URL names our servers have, etc. Basically, everything that is used heavy and on a daily basis. Wrong information will be found out quickly and will be corrected. Needs to be found easy and easy to edit (e.g. online Wiki).

Useless documentation

Documentation which changes often, very few people are interested in it and noone knows where to find it. Like the current state of a feature being implemented. Or requirement documents in a word doc hidden somewhere in SVN, updated 3 years ago. This documentation will take time to write, and time to find out that it is wrong later. You can't rely on this type of documentation. It is useless. It wastes time.

Programmers don't like to write or read useless documentation. But if you can show them documentation which is useful, they will write it. We had gread success with it in my last project when introducing a Wiki where we could write all the information in we need often.

share|improve this answer
add comment

I would say that the main reason is a lack of will and a lack of understanding of the function of documentation. There are a number of classes of documentation to consider:

Product/Release Documentation

This is anything that goes out with your 'finished' product. This is more than just manuals, this is READMEs, Change Logs, HOW-TOs and the like. In theory, you can get away with not writing these, but you end up with a product that people don't want to use, or a support burden that is unnecessarily expensive.

API Documentation

This describes something that should be relatively static. Since numerous consumers may be coding to your API, it should be sufficiently stable enough that some prose describing how to use it has value. Describing what parameters are supported, what the return value can be and what errors may be thrown will allow other users the ability to understand your API at the right level of abstraction - the interface (not the implementation).

Code Comments

The industry opinion on comments seems to be in flux, at the moment. When I first started coding professionally, comments were a sine qua non when it came to writing code. Now, the fashion is to write code that is so clear, comments are unnecessary. I'd hazard a guess that this is, in part, due to the fact that many modern languages are written at a much higher level and it's way easier to write legible code in Java, JavaScript, Ruby, etc. than it was in assembler, C, FORTRAN, etc. Thus, comments had a much greater value.

I still believe that there is value in comments that describe the intention of a section of code, or some details about why a certain algorithm was chosen over a more obvious one (to avoid over-zealous refactoring fiends from 'fixing' code that doesn't actually need to be fixed).

Unfortunately, there's a lot of selfishness, rationalization and self-delusion involved in programmers' decisions not to document. The reality is that, like code, the primary audience for documentation is other people. Thus, the decisions to write (or not write) documentation, at any level, is one that should be made at the team level. For the higher levels of abstraction, it may make more sense to have someone, other than developers, to do it. As for documentation at the comment level, reaching an agreement on the purpose and intent of comments should be agreed upon together, especially in mixed ability and experience teams. It's no good having senior developers writing code that junior developers can't approach. Some well placed and well written documentation can allow a team to operate much more effectively

share|improve this answer
1  
+1 for "the primary audience for documentation is other people". Too many programmers don't really value communicating with others. (That's also why they will find it hard to advance in seniority.) –  Donal Fellows Jul 15 '13 at 5:42
add comment

Here are my two cents.

  1. The Agile Manifesto states "Working software over comprehensive documentation" and not everybody reads on to reach "That is, while there is value in the items on the right, we value the items on the left more."

  2. Sadly it's common to https://en.wikipedia.org/wiki/Code_and_fix and the documentation doesn't work with this model (It gets out of sync).

  3. Software development industry is not regulated well. There is no legal requirement to write documentation.

  4. Self-documenting code is the current trend.

Having said that, I think there is a lot of good documentation out there.

share|improve this answer
add comment

Documentation takes time, and I suspect a lot of developers have had too many run-ins with documentation that was worse than useless. They get the idea that not only will documenting get them trouble from their manager (the same guy who keeps cutting the QA part of the schedule), but it won't help anyone, including them.

Any half-decent bit of documentation is an investment in the future. If you don't care about the future (because you don't think beyond the next paycheck, or because you think it won't be your problem), then the thought of doing the documentation is extremely painful.

share|improve this answer
add comment

Many of the other responses gloss over the point that there are at least two types of documentation: one set for other developers, and a different set for end users. Depending on your environment, you may also need additional documentation for system administrators, installers, and help desk personnel. Each target audience has different needs and levels of understanding.

Consider the (stereo-)typical developer: He is a coder by choice. He has chosen a career out of the public eye and spends long hours behind a keyboard communicating primarily with himself. The process of documentation is a form of communication and the skill set required to produce good documentation is antithetical to the skills required to produce good code.

A good documentation writer can communicate in multiple languages: the language of users, the language of management, the language of support staff, the language of developers. It is the job of a documentation writer to understand what a coder communicates and to translate that into a form that all of the other groups can understand.

When you expect coders to develop the skill necessary to become good communicators (written or otherwise) the amount of time spent honing the primary skill set (coding!) is decreased. The farther he gets from his comfort zone (coding and communicating with other coders), the more time and energy will be required to perform the task well. You can reasonably expect a professional coder to desire to focus primarily on his core competencies, at the expense of all others.

For this reason, documentation (with the exception of inline code comments) is best left to communicators, not coders.

share|improve this answer
4  
Oh, pish. The more things you learn to do well, the better you get at learning to do things well. Just as people who know multiple languages program better than people who only know one (because they know more ways to think about the problem), being able to write and even visualize graphically give you more tools to think about and solve problems. The skills you need to be able to describe what is happening are the same ones you need to tease out what should happen. –  Amy Blankenship Jun 21 '13 at 4:03
1  
I want other developers to be or become skilled communicators. The vast majority of the programming we do (at least in business software) doesn't require the absolute highest honed coding skill set. It requires much better person-to-person communication skills so that future developers understand what was written. The better a developer can communicate, especially to people they'll never meet, the better they'll be thought of in the long run, and not likely for clever code. –  Kevin Rubin Jun 21 '13 at 13:09
add comment

Reading the code shows you how it works. It cannot explain why: you need comments.

Reading the code shows you the name of a method, and the types of the parameters. It cannot explain the semantics, or the exact intention of the author: you need comments.

Comments do not replace reading the code, they add to it.

share|improve this answer
4  
+1 for the sentiment. But this isn't an answer to the question; you seem to be responding to something else here other than the actual question asked. –  bignose Jun 21 '13 at 7:31
add comment

Documentation is not executed as code is. As a result there are often not effective feedback loops to verify that the documentation is in place and is complete. This is the same reason that code comments tend to rot.

Donald Knuth promoted Literate Programming as a way of improving the quality of software, effectively writing the documentation with the code. I've seen a few projects that have used this approach quite effectively.

Personally I try to stick to the modern trend of keeping the public API of your code as readable as possible, and to use unit tests to document usage for other developers. I think this is part of the bigger idea of having your API be of a form that can be explored and discovered. I think this approach is part of what HATEOAS tries to achieve with web services.

share|improve this answer
add comment

A minor point, but one that seems to be important with some developers who write obnoxiously little documentation: they can't type. If you have some approximation of the 10 finger system you tend to write more documentation just because it's easy. But if you are stuck with hunting and pecking you are lost. If I'd be responsible for hiring this is actually something I'd check.

share|improve this answer
add comment

People who dislike reading documentation dislike writing documentation. Plenty of programmers will do all they can to avoid reading a document thoroughly.

Don't focus on the writing, focus on the reading. When programmers read documentation and assimilate things from it, they will see the value and be much more inclined to write some.

share|improve this answer
add comment

When I started my current job and took over a hardware + software project from from the people who had previously been working on it, I was given a hundred or so page ms word document describing the system. It must have taken days to produce. I looked at it maybe twice. Despite the massive amounts of information in there, it rarely answered the actual questions I had about the system, and even when it did, it was faster to look at the code.

After enough experiences like that, you just start to think, why bother? Why spend your time answering questions that people never asked? You start to realize how truly difficult it is to predict what information people will seek in the documentation; it is inevitably filled with facts that turn out to be useless, unclear or obvious, and lacking the answers to the most pressing questions. Remember, producing useful documentation is an effort in predicting human behavior. Just as a user interface design is unlikely to succeed before it has gone through multiple iterations of testing and debugging, so it is naive to think that it is possible to write useful documentation based only on expectations of how people will interpret the system, and what role the documentation and its language will play in that interpretation.

I tend to think that most of the pressure to write documentation stems from the fact that it is an unpleasant chore and people like guilting each other into doing unpleasant chores ("You haven't eaten your filboid studge!").

HOWEVER

I do not think that documentation is, in all ways, hopeless. I think it is hopeless primarily when people look at documentation as this extra burden that must be fulfilled before a job is finished, as a last bit of cleanup work to be hurried through, and as a box to be checked. Documentation is something you should work into the aspects of your day that you always do anyway. I think email is a particularly good way to do documentation. When you add a new feature, write a few people a quick email saying what it is. When draw a new schematic, generate a PDF and send it to anyone who might be interested. The advantages of email are:

  1. People usually check email, whereas no one wades through a folder called "doc".

  2. Email exists in context, surrounded by other emails discussing the feature and related features and anything else that was going on at the time.

  3. Email is short and focused and has a subject line.

  4. Email allows the people who care to ask questions right away,

  5. Email is highly searchable, because people use it for everything and mail clients have advanced quite a bit over the years.

  6. If it's in an email, at least one other person knows where to find it.

In theory it should seem that comments in code should also be "aspects of your day that you always do anyway", but to be honest, I never read comments in code. I'm not sure why, but they're just not very helpful, maybe because there is a lack of context, which email solves.

share|improve this answer
    
except for #4 ("people who care ask questions right away"), none of email benefits you list has been reliably working for me. 1: People tend to ignore email, when there's a lot of it 2: Email frequently tends to lose context, burying it in side-issues and overquoting 3: Emails are way too often long/large and tend to lose focus as discussion gets into more side issues and subject lines are often irrelevant / obsolete ("Re: WTF happened on server today?")... –  gnat Jul 15 '13 at 3:47
    
... 5: Email search is highly compromised by the ability to delete mails, a feature any decent mailer has and any active mail user well, uses a lot 6: see 5, if the mail is deleted, no one will be able to find it (the only thing I can rely on is searching my sent mails and this is only because I try very hard not to delete these). Other than email praise (which looks quite unjustified to me), you make some good points though –  gnat Jul 15 '13 at 3:47
    
@gnat I suppose it might vary company to company about deleting. At my company we save all emails, plus archives of all emails from past employees, and whenever a new person starts on a task we forward that person all the related emails. I suppose a difference in style. –  Owen Jul 15 '13 at 3:50
    
yeah, that depends a lot on the style / culture. While "fighting deletion" is certainly doable (and even technically simple to achieve by exporting mail threads to some server), things like keeping them focused, subject lines relevant, quoting limited to reasonable limits is highly cultural thing, requiring quite a lot of effort and determination (and management support) to maintain... Compared to this effort, and especially to the need for mgmt buy-in, maintaining stuff like wiki / code comments / doc folders may turn out just easier –  gnat Jul 15 '13 at 3:59
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.