What documenting expectations can developers reasonably fulfill?

Question

I work at a growing company where developers were doing customer support. Now, that our customer base is growing and we're trying to get the documentation the support staff needs in order answer the questions for the developers.

So, In a normal day, how much documentation can be expected of developers. What kind of documentation?

Are comments in code considered documentation? (should we pull those out automatically?)

As our developers are programming changes and new items, should someone else do the documentation?

What's typical in the programming profession for documentation expectations?

Answer 1

Developer's should be required document their own work. (At my last job they tried to hire someone to do this, and guess what happened, none of it got done). They need to write down what the system does and why. Comments in code aren't enough. Someone else should be able to pick up the documentation and tell what changes are in each release and why, even if only at a high level. We use Wikis for all of this. All updates are logged, screen shots taken and affected modules noted.

Steve McConnel talks about this in Code Complete. He states (and I frimly believe) that all technical documents about what changes are made and developed are written before actually writing code.

That being said, this is different than writing user manuals as to how the system works for the end user. You'll probably want to hire someone to create a professional looking, well written document for that.

Answer 2

The bottom line is you really need to crystallize what your users need to know in something that makes since to them. How do your users use your product?

If your users are domain experts, you need to gauge how they are using your tool. The best thing to do would be to hire a domain expert to become an expert in your tool (an expert user) and he or she will do the best job describing to your users exactly how to use your tool to complete a domain task. They can be involved on a daily basis providing good feedback on the tool, and be involved in the documentation phase. Without a domain expert, your developers need to gain a good level of domain expertise and be able to understand things from a black-box perspective. This may not be so easy from the nuts-and-bolts perspective of development. The added benefit of a full-time domain expert is that you have the yin of the black-box perspective contrasting from the yang of the nuts-and-bolts guys. This will help you tremendously in documentation, as well as a myriad of other ways.

If your users are other developers (you develop an API/SDK) than you can use code comments. This means you need to have more professionalism and higher consideration of what kinds of comments you provide via the interfaces to your API. You may wish to hide the "internal" comments and only expose the comments that are part of the programmer's interface. You can use tools such as doxygen to manage this. Even in this case, it might be good to have a domain expert. So if you were writing a library of math routines for rocket scientists, the other rocket scientist programmers are really going to get their best understanding from another rocket scientist programmer. Sometimes, though, your users might just be people doing the same thing as your developers, so your developers might not do a bad job.

Answer 3

Set up a wiki server using MediaWiki software and declare that this is the definitive source of information for how your product works. Have the support staff look at this wiki as their first place to ask questions. When information they need is lacking in the wiki, have them file a request for it to be added with the programming staff and get management to prioritize that task appropriately. When information in the wiki contradicts what the product does, have them file a bug with the programming staff, and again have it prioritized appropriately.

When the programmers are assigned a development task, have them sketch out a rough draft of how it should work in the wiki, first. Encourage them to look to the wiki for their questions also, and to record things they learn there.

No, code comments are not documentation. Code comments are for developers, not support staff or customers. They might explain the guts of how something works, but typically not in a way that your support staff will need while dealing with customers. If they do contain such information, that should also be migrated into the wiki.

The only thing that might be in your code that would qualify as documentation would be API documentation, and then only if your product is a library or module used by other programming shops. So, POD for Perl, Javadoc for Java, etc. This kind of documentation should be included regardless, but it's generally not something relevant for your support staff unless you are providing a library.

Answer 4

If you code it, you must document it.

Always try and think of The Next Guy.

Answer 5

I only know what I've experienced in the last 12 years of developing software, can't speak for the whole industry. I know that it varies with the size of the operation and the importance that the team puts on governance. In one of my groups, we were building applications for medical instrumentation that was going to ultimately be FDA regulated. We knew that, so writing complete and accurate technical specifications before and after development was part of the process.

At the small start-up that I recently left, we documented nothing, beyond comments meant for the other developers.

Answer 6

Ideally you have an intermediary between the developers and the support staff/users writing the documentation. Someone that can take the technical mumbo-jumbo and express it in ways that the support staff and users can understand. Like the movie says, developers aren't very good at dealing with customers ;)

Perhaps you could use some sort of wiki or shared knowledge base that everyone can access and update? I agree with Kevin that comments in the code aren't enough. It's usually the checkin/commit comments that mean more (what was changed, why it was changed) and/or comments in your defect tracking system.

For customer support FAQs, trouble shooting checklists and support guides help. These are usually created and maintained by the folks that do the support.

For technical documents about the system architecture, design and such, technical writers can help, but the bulk of this should be written and reviewed by the developers, with the tech writers doing edits for readability and style.

Answer 7

Ah well we hate to write documentation! :)

No but seriously, comments in code are definitely documentation as long as they're useful (things like "don't touch this EVER" can't really count). There should be comments every few lines in the code especially in long functions/methods or when it isn't perfectly clear what the purpose of the code is.

In Java for example, it should be a requirement to have Javadoc-type comments in all methods, classes interfaces, enums, and even some fields. That will allow anyone to generate the technical documentation for any application, library or framework they need to work with, and most IDEs nowadays can parse that info and give contextual help with classes and methods. I think .NET has similar features with triple slash comments on methods, classes, fields, etc.

But besides that there should be some higher-level documentation stating the purpose and scope of libraries/frameworks as well as some examples (a sample application can be considered documentation since its purpose is to illustrate the users as to how the library/framework works and what it does, although in this case the users themselves are programmers).

I think user manuals should be left for other people to write. Letting us programmers write that kind of stuff leads to horrible manuals that are barely understandable, and I think it's because we usually know the insides of the application and are thinking in terms of the software, not the user. User manuals should be written by someone who knows how to redact well, someone who has learned how to use the application but doesn't exactly know how it works internally (unless they really need to know because the user will need to know). How to install it and configure it in different environments, etc; QA people are better suited for that, IMHO.

Answer 8

If you expect zero documentation

your expectations will likely be met. Doctorow's Metacrap thesis sheds some light on this. See also Rorty and His Critics By Robert Brandom, page 99 paragraph three.

If you really want good documentation, make it as easy and enjoyable for your developers as writing the code itself (arguably impossible if you concur with the above referenced materials), or hire someone whose job is to do nothing but that.

Answer 9

The best and the easiest solution is to hire a technical writer who has knowledge of software development. This would make the documentation process a log easier and quicker. Technical writers are considered as the best option as they are far more knowledgeable when it comes to writing the development process in simple English that can be understood by anyone.

Comments between codes are often used to briefly explain what the happens next in the program and cannot fully be considered as documentation, however they will come handy when a technical writer prepares a developers manual.

Cheers, Eddie Gear

Answer 10

Ideally, a lot of the documentation should come BEFORE coding has started. This helps the developers by planning what they will be doing more concretely, and is something you can hand to support after code is written.

This documentation should both answer the following questions:

1: What the problem you are trying to solve is 2: How it can be solved 3: Why you chose the solution you did

This sort of information (or a subset of it) can be useful for support, the developers writing the code, and future developers coming on board so they can understand the thinking that went into a feature they may have to deal with in the future (particularly when the developer who wrote it is no longer with the company).

Automatic doc generation (a la javadoc, doxygen, etc) has its place, but that place is not usually for communicating with support -- it's developer to developer communication, usually.

Answer 11

Since you are trying to write documentation that support people will use to help customers, programmers shouldn't even be a part of the equation. It's very possible that the developers will come up with great and relevant documentation but I don't think it's very likely.

A good technical writer or just a good writer in general that knows the software well would be a better choice to write what sounds more like a user manual.

Answer 12

In addition to the other answers here, always keep at least one developer involved directly (part-time) with support. That way they will have a lot more empathy for both customers as well as the support staff and be able to spread that empathy to the development team. You can try rotating different developers in and out of this position accordingly.