[Coco] DW4 on MAc & Linux

[Al Hartman]

> This type of "hold your hand" documentation is great for new users,
> and when developing commercial software it can be a big selling point
> and revenue generator.

People will buy a product sight unseen. They don't see the documentation 
until AFTER they buy the product. Most customers never see the reviews.

> When creating free software, there is little
> motivation to do such things unless the author just enjoys doing it.
> Most do not, myself included.  However, it is very common with open
> source projects to find how-to and step by step guides created by
> users who like doing that sort of thing.  When we are talking about
> free software intended for use by hobbyists, it is difficult to
> rationalize anyone doing anything that they don't enjoy.

I don't mean to upset you, but in life one often has to do things one 
doesn't like.
Especially to do a good job. If I'm doing something I expect others to use, 
I need
to make the documentation as easy to understand and as useful as I can.

That is as important as writing code that works.

>> I had to experiment to find which .wav file to use to get my Coco 3 to 
>> load.

>> I found the Drivewire "documentation" on the Cloud9 site useless. It 
>> assumed
>> so much knowledge on the user's part (like what files to use), that I 
>> found
>> no answers to my questions in it.

> I reviewed the Cloud-9 documentation again.  Here is a trimmed quote
> from that page:
>
> "If you do not have HDB-DOS or DW3DOS burned into ROM, then the
> quickest way to get your CoCo running DriveWire is to use one of the
> supplied .WAV files...
>
> ...To get started, you must choose which .WAV file to load:
>
> If you want to run HDB-DOS, your CoCo 1 or 2 must have Extended BASIC
> and 64K of RAM; you will need to queue the hdbcc1.wav or hdbcc2.wav
> file in your favorite music player on your Mac or PC. CoCo 3 users
> should queue up the hdbcc3.wav file.
>
> If you want to use DW3DOS to boot right into a NitrOS-9 disk image,
> then your CoCo 1 or 2 must have 64K and you will need to queue the
> dw3doscc1.wav or dw3doscc2.wav file in your favorite music player on
> your Mac or PC. CoCo 3 users should queue up the dw3doscc3.wav file."

> Prior to this quote is information about using WAVs vs ROMs, and next
> the docs talk about how to use and adjust the audio source along with
> the CLOADM command on the CoCo.

> I must say I am at a loss to how these instructions have failed.  They
> specifically explain what the files do and what is required and what
> file to use on which model of CoCo.

These paragraphs do not exist in the documentation file that you get by 
clicking on the "Documentation" link at the top of the Drivewire page.

If they exist elsewhere, a new user won't find it, because they will assume 
the documentation file at the top of the Cloud9 Drivewire page is THE 
documentation file, and is authoritative.

Maybe you have a link to another file. I didn't. I assumed that the link on 
the page was the one I needed.

I'd give you the link, but the link in my address bar never changes from the 
Cloud9 website address.

> I'm sure Cloud-9 would be happy to improve this documentation, but
> again I'm sort of lost on what that would mean.  Specific examples
> would help.

>> I had to experiment with Drivewire 4 to get the right settings for it to
>> work.

> I am interested to know what settings were not correct when you
> completed the setup wizard, or if it was that a step in the setup
> wizard did not make sense.  I can fix this if you let me know.

For example, I had to know to turn on the HDB-DOS translation. I wasn't 
asked if my client was going to use HDB-DOS or OS9.

I wasn't told to exit the server and restart it after saving the changes. If 
I hadn't read the thread here, I wouldn't have known to do that.
If you can't fix the code to apply the changes immediately, an instructional 
dialog box is the next best thing.

-[ Al ]-