Channels ▼

Christopher Diggins

Dr. Dobb's Bloggers

Effective use of Programming Writers

May 21, 2008

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.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.