Re: gEDA-user: PCB & Gschem

["Charles Lepple" <clepple@xxxxxxxxx>]

On 2/24/06, Marc Price <mark.price13@xxxxxxxxxxxx> wrote:
> Im not reading Bill Wilsons Tutorial I Dont Want to be influenced by it
> im Writting my own

As I see it, there are two approaches to writing good documentation:

1) Start off as a newbie, and write down everything you had to do to
get things working

2) As an expert on the system in question, write down everything you
think a newbie would need to know.

Problem with approach #1: many newbie-written tutorials miss out on
helpful shortcuts, or similarly, contain a lot of "I didn't know how
to do this correctly, so this is what I did instead" procedures. As a
newbie (I'm not picking on you in particular, Marc, just commenting on
new users in general), you may not have much insight into the "big
picture" on how the system works, or how to diagnose problems that you
encounter, and therefore someone is going to have to spend a while
reading your documentation to fully understand it.

Problem with approach #2: if you're an expert, how are you going to
know what is essential for a new user? (Again, I'm not picking on Bill
Wilson's tutorial, because I personally think it strikes as nice
balance between being simple to understand, yet written with a good
technical understanding of the system as a whole. YMMV.)

So how do we meet in the middle? Simple - work with what is out there
already, instead of reinventing the wheel. If you're new to gEDA and
PCB, read an existing tutorial, *and* take notes on what is missing,
incorrect, or just plain hard to understand. For instance, if you
think you have a better way to present Bill's tutorial, tell him. It
will take a lot less time to help him improve his tutorial than
writing your own tutorial from scratch, and it will save other people
from having to wade through several tutorials just to get past the
first part of the learning curve.

--
- Charles Lepple