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

[Brian Blake]

In helping write the manual for the CoCo SDC, I snagged a lot of info from
Darren's blog - which I would assume is mostly his tech notes, as Bill
mentioned. Also, I took time expanding on that with examples of my own
experiences with the device, as well as (hopefully) useful examples.

Obviously all of the hard core techie stuff was Darren's.

------------------------------
www.tandycoco.com
www.tandycoco.com/forum

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



--
Coco mailing list
Coco at maltedmedia.com
http://five.pairlist.net/mailman/listinfo/coco