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

[Juan Castro]

Excellent! This, sir, should be an article. Then you could ignore that
Dennis fellow.


On Thu, Feb 20, 2014 at 11: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
>