Effective use of Programming Writers
I am currently working on contract for Microsoft as a programming writer. Many people in other organizations aren't aware that such a role exists, and those that do often don't realize how much more effective they could be if used properly.
A programming writer is someone who writes programming guide and API reference guide material for APIs and SDKs, including the API reference material. They are sometimes write programming guides, and example code. Often they are also called on to write white papers and stand-alone samples.
To be an effective programming writer, one would ideally have a programming background, be a fast learner, have a certain amount of project management skills, and have basic writing skills.
The way programming writers are typically used, is that they are brought in at the end of an SDK project a month or two before it will ship and told to document the APIs, and write a programming guide. They will typically have to beg and plead for access to the development team's specifications, access to the source code, and for the public facing headers and IDL files.
Once the programming writer has the core materials, they have to plan the documentation and try to get the developers and project managers to sign-off on the contents of the documentation.
After the content is written it is shipped to members of the development team that agree to perform a tech-review. Usually at this point, the requests for change to the documentation and new material is huge. This is because the programming writers simply did not have enough time to get familiar with the technology, and the participation during the documentation planning process is minimal.
Sometimes after a tech-review, the development team will overhaul the API from top to bottom, because previously no one had a clear high-level picture of how the SDK works. This indicates quite clearly how useful good documentation if incorporated earlier on in the development process.
Programming writers can be very valuable members of a development team if they are incorporated into the team from the beginning of the development process. I propose that they should be attending design meetings, writing the design specifications, writing the documentation for the public facing code (headers and IDLs), and writing samples as high-level usability and functionality tests.
This would lead to faster and more affordable documentation delivery, as well as a smoother development process. Not only is some of the burden of writing design specifications removed from developers and project managers, having good documentation can improve development because other team members can use the documentation, and rely on it being up to date. No more surprises about the API design that occur only at a last minute documentation review!
If you are a manager of a development team for an SDK, you would be doing yourself a huge favour if you brought a programming writer in from the beginning and kept them as informed and involved in the development as possible.