The Documentation Process

I thought that I might post a brief discription to the process of how the documentation that I am working on is being created, so that everybody is familiar with what I am doing.

Step 1 Research

Since this is an introduction to programming using a “higher level” language such as Processing, my research revolves more around a practical approach to understanding most modern day higher level, programming languages.

Amongst the languages I've been cross-referencing in my personal notes for this project other than Processing is Flash ActionScript, Python and C++.

In formatting the documentation for this module I aim to take special care in addressing Processing within the context of these other languages, what I mean by that is,

• for example when naming conventions differ between languages I'll note the alternate names and as each language emphasises and favours a particular concept over another languages approach, which address programming with a different set of utilities. I aim to identify these differences and provide the reader with an outline of why the approaches to dealing with programmatic situations differ even though the outcome might be the same.
• Various publications and online resources have been particularly helpful to me during this phase of research. The results of this research is approximately 50 pages of notes, in keyword form. Which then have to be cross-referenced with the other above mentioned languages. When the methodology differs significantly for doing similar things from one language to the next, I simply have to make a choice as to which method I find to be most sensible within the context of what this documentation aims to convey (ie a sense of understanding higher level languages). 
  

Although the method I choose to emphasise in my documentation might not be the quickest and require the least amount of keystrokes, using programming shortcuts and “tricks” is not what this module is about. Subsequently those that are more serious about programming are encouraged to discover these shortcuts, tricks and special techniques themselves to help develop and further their own skills as a programmer.

Here's a look at what the written notes look like.

 

This page is about creating arrays in Flash, this method differs somewhat substantially from the C++ methodology. In my notes I'll be emphasising the latter in Processing.

 

The second page is an example of syntax differences. Of course in addressing several different languages there are going to be many differences in syntax which subsequently overflow into methodology. What I am attempting to do with my documentation is not to focus on syntax as much as I aim to focus on methodology. The main reason for this being that good, solid programming principles can be applied to any language and adapted to suite any syntax that exists in a language of the same level. Another reason is that learning a language's syntax these days is pretty easy with the advent of the large amounts of free documentation and forums online for each specific higher level language.

 

Finally the third page is an example of an exercise for the reader to complete using the information learned in the preceding documentation. Documentation such as this can only be created once the other research has been completed and cross-referenced, particularly as the exercises must be as generic as possible (in terms of language differences), yet still specific enough for the reader such that one needs an understanding of the most relevant concepts of the preceding documentation in order to complete the exercise.

Step 2 Unformatted Documentation

Once the research has reached a level that I am pleased with, I can continue to create an unformatted version of the documentation. Step 1 does not need to be completed in it's entirety in order for me to start with Step 2 and I will constantly jump back and fourth between these two Steps refining each one until I am finally happy with the product and able to move onto Step 3 creating the formatted version of the documentation.

In the unformatted version of the documentation I basically read through my notes and think of the best way to deliver an understanding of a concept to the reader. I then proceed to type out this thought without editing it. Subsequently one paragraph might seem disjointed and non-contiguous from the next, so a lot of restructuring of the documentation needs to happen at this stage.

Here's an example of what the unformatted version of the documentation might look like

 

As you can see a lot of typing errors and bad punctuation, unpollished illustrations and minimal formatting make up the unformatted version of the documentation. Nonetheless everything that I need for the completed version is pretty much all there. 

Step 3 Completed Documentation

The completed version of the documentation has the correct formatting, that makes sense from one paragraph to the next. The paragraphs will also have an appropriate word count such that a few words are not left trailing behind on an entire page for themselves. The images are completed, and sized accordingly, and code listings are also taken into consideration such that they do not extend over multiple pages (unless the listing is excessive).

Here's an example of completed documentation from a previous project

In this example each code listing (which can also be referred to as a code “snippet”) is enclosed in a table, I'll be using a new format for code listings in my current documentation project which I feel will be easier to read and more visually appealing.

Here's an example of an exercise from a previous project

Once the project is completed the documentation (as with previous projects) will be freely available online with the exercises and distributed under a Creative Commons license.