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.

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.

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?

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.