By Jon "maddog" Hall
A friend of mine who runs a free software consulting business was lamenting that when he asks his engineers if a project is "finished," they often reply "yes." Yet when he goes back to check the work before invoicing the customer, he finds no or inadequate documentation, no evidence of quality checking, and no communication with the developers of the original source code for inclusion of the changes to the software. In short, the work amounts to a quick "hack" instead of a finished work.
Unfortunately, this happens a lot with software developers, and often those who are hired from "the community." Used to working on smaller projects in which "the code is the documentation" or for end users who do not pay a lot of money for working software, they do not have the experience or rigor necessary for larger projects or commercial code production.
With the very best programmers, projects start before the code is written by making sure that the requirements of the customers are well understood. Timelines are written for the work process, which includes time and resources for quality assurance and documentation. Afterward the design is considered, the code is written, and then the "real work" starts.
Quality assurance (QA) has to be done, even for the smallest change or program. Most of the time this kind of testing is best done by someone other than those who wrote the code because QA testing by programmers is tainted by their views of what does and does not need testing and their belief in their own programming skills. Also, a different person might create test cases far outside those test cases programmers would create for their own code.
Documentation is another example in which another person with different skills and viewpoints might do a better job than the original programmer in creating usable documentation for new code (or changes to old code). Documenting the "intuitively obvious" is often what makes the difference between usable documentation and documentation that is of no use at all.
In cases of QA and documentation, the programmer has to create detailed "bullet points" to tell the QA and documentation people what has changed and how those changes affect the previous code and to suggest what needs to be tested and documented. Later, the programmer and project leader should review the QA tests and test results, as well as drafts of the documentation.
In smaller companies and projects, the same person might do the programming, the documentation, and the QA, but those actions have to be done. On the other hand, this is where "Free Software" can really leverage off the use of community members.
Many times I hear the lament of end users saying, "I cannot help because I am not a programmer." Yet these same people might be good writers or (assuming the developers tell them what has to be tested) good testers.
With the use of modern online collaboration tools such as wikis, for example, there's no reason why end users of Free Software could not contribute to good documentation. If you read a section of the documentation on a wiki and you do not understand it, once you figure out how the software works, try editing the online documentation to make it clearer.
If, as a customer or user of Free Software, you are following a particular project and like what the programmers are doing, try testing new releases of the code, concentrating on testing what the programmers have changed, as well as the overall functionality of the system. Yes, this might require that you learn how to use a problem-reporting and tracking system, but learning that problem-reporting system is part of your contribution to Free Software.
Interestingly, when dealing with some "professional" closed source companies, you have to PAY for the "privilege" (sometimes as much as US$ 500) just to submit a bug report, much less get any bug fixes or workaround advice.
Of course, team leaders or project managers are the ones ultimately responsible for the overall quality and "completeness" of the program. They should explain the ground rules for developing code inside of their projects as each programmer starts and that those rules include a high standard of testing and documentation.
I told my friend all of this as he was still shaking his head about his own company. He said that he would have a talk with his programmers about creating world-class software. I mentioned that I would write this article, and perhaps his job would be easier.