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

[Mark McDougall]

On 21/02/2014 1:33 AM, Bill Pierce wrote:

> 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.

Otherwise known as a Requirements Specification.

> 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.

And when applied to all aspects of the design, and not just "problems", it's 
known as a Design Description.

> 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.

Which is in part how large firms, that can employ technical writers, 
approach the task of writing manuals *along with other inputs).

> 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.

Just as the process of maintaining RS's and DD's should also be kept up as 
the project evolves.

> Personally, I like writing manuals and enjoy putting it all together.

Ughh - not for me! :(

I would like to commend you on such a disciplined approach Bill! We follow 
this process at work for every project, and if I'm working on anything major 
myself at home I also attempt to do the same, especially where I'm hoping to 
enlist the aid of friends/colleagues. I can't say that I've ever been a fan 
of producing any sort of documentation; not because I don't believe that 
it's necessary/useful - it most certainly is - I simply don't like doing it.

Regards,

-- 
|              Mark McDougall                | "Electrical Engineers do it
|  <http://members.iinet.net.au/~msmcdoug>   |   with less resistance!"