Documentation and Software Quality
Like most developers out there, I have to write some user documentation once in a while. After a few weeks of intensive development, a few days have to be spent documenting the new features. It just has to be done, otherwise I will get stormed with questions once the beast is released. While I write the documentation, a few empowered expert users already begin to use it. Documentation probably wouldn’t take so long to write if I didn’t have to listen to all those comments.
Writing user documentation takes a lot of time, but it might be worth it for the software quality. I write the documentation based on user tasks and the expected behaviours of the system. The process of documenting itself forces me to perform some validation. Multiple questions come up when you attempt to write down words that end users will eventually read.
- Is the term used appropriate? Is it consistent with the rest of the application?
- What is the data input format exactly?
- Is there anything that could be unclear?
- What are the exceptions? How can they be differentiated?
- I know how the information is used by the system, but what value does it add to the user?
Most of these questions can be answered by testing and peeking at the code to verify the exact rules implemented. For others, the early adopters can be of a great help. They already have a global understanding of the system (mostly because they were involved early in the development cycle), but they know the exact details and can offer this very first impression in an articulated way. The goal is to find the picky one in the group. While they are mostly annoying when the application is in production and you moved to the next problem, during this phase, they provide the comments that have the most value.
The element that makes the largest different is probably the act of documenting itself. The perspective moves away from code, design and data. By focusing on the user’s process and the tasks to be performed, you can focus on what the real needs are. Examining the tasks was probably done very early in the development, but when you write a few hundred lines of code in a day with the clear objective of delivering features, these user-oriented thoughts often slip away.
As you get a new perspective, you get to understand what matters the most to the users and can write something that makes sense. Most of all, you get to see what does not quite make sense in the application. Those minor interface improvements suddenly appear. Sometimes, changing the order of a listing, changing a label or even adding some spacing can improve usability, and substantially reduce the amount documentation to be written.
I noticed the developed software is a lot more polished after writing documentatiobeneficn today, but when looking back, it happened in the past as well. A few years ago, I contributed an on-line spreadsheet to Tikiwiki (which was surpassed long ago when google-style pastel-colored ajax-powered applications started to appear). The interface was always a little clunky, while I could generate graphics out of the data, I was probably the only one who ever got to make it. At some point, I was asked to write documentation. When I got to write it, I made a few commits on CVS just to simplify the documentation I had to write. It’s not that good of an example, because TikiSheet’s interface is still the worst spreadsheet interface around (some damage can’t be undone so easily, and it’s not like I had that much time to spend on it anymore).
Some say documentation would not be required to understand how to use an idea application. Unless you have a few usability experts working on the project and people with perfect knowledge of the user tasks, along with a clear vision of the final product, it probably can’t be achieved. Software improves as it gets used. I think writing documentation of sufficient quality can be a good first step to improving the interfaces.
Since, like most programmers who don’t have a complete crew of experts to support the development, I have to place some focus on development and get some work done. Spending around 20% of my time writing documentation, and validating the application at the same time, sounds like a good compromise. As a benefit, I can release a more polished application to the end users.
This would probably not be possible if the documentation was written by anyone else than the developer. It could be possible, but only if the developper is open to comments during that period and ready to make the small insignificant changes. Of course, this is not likely to happen. In fact, one of the only reasons why I actually make those changes now is that it can potentially reduce my documentation workload. It’s also because once I spent over an hour writing documentation, moving to anything else, including apparently insignificant changes, is a good option.
What I really am wondering about is if writing developer documentation is all that useful. If the simple fact of writing documentation places a focus on quality, is it really benefic? I remember assignments in the first design courses at university when we had to write reports to explain our design decisions and the patterns used. Of course, it was for educational purposes, but the design that came out of those assignments was so pure and flexible that it would make it more complex and unusable. Writing developer documentation places the focus on technical aspects. I have no doubts it can improve the design as they teach in the textbooks, but is it really what you want? Think about it in a different way, is it really what the person sponsoring your development need?
These statements probably classify me as a software engineering heretic, but I really don’t think code needs documentation. If the application’s design is consistent, the developers that follow only need to understand the base layout to find out how to perform modifications. If each component’s design is close to perfection, but every component has it’s own specialized flexible design, the learning curve ends up being much longer.
Placing the focus on object oriented design tends to create applications that are far too expandable. Concepts are generalized even if they are not likely to be used in the future. If a single concept is forgotten (you know the forgotten concept is the one that will be needed, right?), the whole design is only making the modification harder. Not only you waste time designing, but time was made implementing extra layers of complexity to make every single class absolutely simple. Then the relations between all those classes and objects have to be documented. What does it take to document an object model? A whole lot more than text. It takes graphics and diagrams. To get these done correctly, you need specialized tools. In the end, it takes a lot of time and does not provide that much value.
Face it. No one likes reading documentation. I don’t know many developers who willingly grab a software’s documentation an read through it before attacking development. Documentation is the fallback plan. It’s the fallback plan for the users who can’t accomplish their job by simply trying the application and it’s also for the developers who don’t see where to plug their new features. The reason why end users fall back to the documentation is that they end up being completely blocked. Applications developed for end users are a lot more restrictive than a programming language. Programmers are likely to destroy a huge part of you well planned design before they end up being blocked. They might never even notice there was documentation written in the first place.
The goal of a software developer should be to provide a solution. Focus should be placed on the results, not on internal details. Writing user documentation allows you to validate user requirements, improve the interface provide a fallback plan if you interface’s simplicity fails.