[Coco] First experiences with my DE1

[Bill Pierce]

I was going to stay out of this one as well until Art spoke up.
I disagree to a "certain" degree.

First.... A newbie writing the manual? That's Like I send you a copy of my current project and tell you to write me a manual.... or better yet... just run it :-)
How can someone with no knowledge of the software write a manual? Yes, once one is familiar with the program and has some knowledge of the inner workings, then yes, they could write a manual.

The author/developer at least needs to keep some notes, command trees, installation instructions....
Without some sort of beginning, the is no where to start. I'm not saying they need to write the manual, but they do need to have a part in it... it's their software/hardware.
My current project has over 125 menus buried in main, sub, and sub of sub menus. There are points where there are special keys that will do special things, these are not in any way marked in the GUI... to run this without a manual, you would miss half the functionality of the software.
I have written a manual for every piece of software I've released and some I haven't released. I don't expect anyone to understand my whimsy nor write it for me.
I feel if I'm going to offer something to the public free or commercial, I at least owe them some instruction for using it. For without instruction they will not get full benefit of the thousands of hours of work I've put into this labor of love and then I will not get the attention that I was striving for to start with. And isn't that what we do it for in the end? The attention.
You ever think that "maybe" this is why the Coco community is in the state of non-popularity that it's in? No one can figure out how to run the stuff you're producing. If it's meant for your own personal use then don't put it in public and expect someone else to finish it for you... or question how to run it.. or how to install it.

As a professional musician, I have played in many bands, some of which I required my fellow bandmates to play some of my original compositions. Now how would it sound if I stepped on stage with a a bunch of musicians who not only have no sheet music to my songs, but they're never even heard them. It would be a disaster. Any time I've required someone to play my music, I've provided chord charts, sheet music, and/or drum charts PLUS a recording of the complete song.
And most of all, after spending many hours composing the music and doing the arrangements, I didn't say "Well I wrote the song... you can figure it out..."
I would be out of business.



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




-----Original Message-----
From: Arthur Flexser <flexser at fiu.edu>
To: CoCoList for Color Computer Enthusiasts <coco at maltedmedia.com>
Sent: Sun, Feb 16, 2014 7:01 pm
Subject: Re: [Coco] First experiences with my DE1


I was going to disagree as well, but now that Al has done so, I'll just add
my voice to his.  Some developers are lousy manual writers, and some are
very good at it.
For the lousy ones, the problem might sometimes be that they are too close
to the product and assume incorrectly that readers grasp something that
they find obvious.  Other times, it might be that writing with clarity is
just not one of their skills.  In-depth familiarity with the product
would be a strength for a manual writer rather than a handicap in many
cases.  If feedback on the documentation is sought while the product is in
the beta stage, many shortcomings can readily be remedied.

Art


On Sun, Feb 16, 2014 at 6:50 PM, Al Hartman <alhartman6 at optonline.net>wrote:

> I don't agree.  I wrote the user interface and the manual for the CoCo
> Greeting Card Designer, and many other Zebra products.
>
> What you have to do is sit down with the product on one side, and your
> word processor on the other and simply go through the steps of using the
> product explaining each decision point and the consequences of making each
> choice.
>
> Then, you can do a step by step straight through walkthrough of bringing
> up the product using the defaults as a quick start guide.
>
> It's easy. My manuals always get well reviewed as being thorough and easy
> to understand.
>
> -[ Al ]-
>
> -----Original Message----- From: Mark McDougall
>
> The developer should never, ever write documentation for users, or other
> developers, and there's very good reason for it. It's not the fault of the
> developer, but of the process.
>
> --
> Coco mailing list
> Coco at maltedmedia.com
> http://five.pairlist.net/mailman/listinfo/coco
>

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