[Coco] A little more on manuals and developing new hardware/software

[Bill Pierce]

Stemming from our previous discussions on writing documentation for hardware/software, I would like to share some things I've experienced in writing manuals for my software.

First, I start my manuals before I start my software. In most cases, I have little more than a layout for the program or notes on planned features, so my manual will look more like a blog than a manual. In fact, the introduction sections to my blogs on my website are just that, my design notes on what I plan to create. I continue these "notes" as I start the project and try to at least jot down any changes, plans  or additions. Not only does this help me keep my progress on the program documented, but it also serves to note any early ideas that have yet to materialize in the program. Sometimes in reading through these "early" documents, I find features I had planned but had forgotten in the writing process.
As the program progresses, so will my manual / tech notes.

Then you get to that routine that no matter what you do, it doesn't seem to work as planned. I usually document these efforts and a lot of times, in writing my documentation notes, that is where I'll see the error in my program logic and not in the programming itself. I find that writing down my problems gives me a 2nd view as I will look at it differently from the documentation angle and see things I don't see when looking at the code. I have solved a lot of my programming problems in this manner. A good example of this is my "MShell" blog. I was trying to figure out how to implement the "virtual memory" data storage and in writing my blog and reading it back, I found the answer to what I was trying to do. I now have virtual memory working perfectly because of writing out my ideas.
It's similar to asking someone how to do something and in asking you realize the answer to your own question just by how you phrased the question (one of those "duh!" moments),

At this point, the documentation looks nothing like a manual, but does have a structure of sorts and is basically "tech notes" in a structured form. If I keep this up till completion of the project, I usually have enough notes to easily arrange it all into a cohesive manual format.
It is also at this point that for developers who don't like to write manuals, they could turn these notes and software/hardware over to someone who could test the project and organize the notes into a readable manual as many have suggested.

As a final step, I will print my manual out on paper and see if it looks like something a newbie could understand (and "spellcheck" is your friend). I try to never assume that someone knows a single thing about my project (and usually, they don't :-) so I try to make my directions complete. First I do an intro to explain what my project is and what it does. I then try to include a step by step from installation to complete menu trees, explaining where each choice leads to etc. I also try to include any "control key" instructions for controls that can be accessed with keystrokes (or clicks) without the use of menus. I've found that sometimes, creating a "menu tree" with explanations of each menu choice will sometimes cover most of the functions of the project. It's definitely better than nothing.

Writing a manual or tech notes should not be a "huge task" you take on later, but part of the creation process from the beginning. Sometimes, just notes on your progress can go a long way to explain things in your project. At least a good "readme" document could evolve from this.


Personally, I like writing manuals and enjoy putting it all together. I also love doing graphics, screenshots and diagrams. Having 5 years of art and 2 years of drafting helps there. Even in writing my software, I will sometimes spend hours on my GUI making sure things are centered, display formats are uniform and menus appear where I think they should (excessive compulsive??). To me, the manual is just an extension of this type of editing.

I'm sure others have more they could add to this and I know I could go on in more detail, but Dennis says "keep it short" so I'll stop here.
I hope this was helpful to someone and didn't bore the rest of you too much :-P


Bill Pierce
"Today is a good day... I woke up" - Ritchie Havens
 

My Music from the Tandy/Radio Shack Color Computer 2 & 3
https://sites.google.com/site/dabarnstudio/
Co-Webmaster of The TRS-80 Color Computer Archive
http://www.colorcomputerarchive.com/
Co-Contributor, Co-Editor for CocoPedia
http://www.cocopedia.com/wiki/index.php/Main_Page
E-Mail: ooogalapasooo at aol.com