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

[tim at franklinlabs.com]

Test - Sorry for the post... Please ignore... Last one. Trying to fix an e-mail
problem with Network Solutions.


On February 20, 2014 at 9:33 AM Bill Pierce <ooogalapasooo at aol.com> wrote:
>
> 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