Re: gEDA-user: PCB & Gschem

[Karel Kulhavy <clock@xxxxxxxxxxxxx>]

On Sat, Feb 25, 2006 at 01:19:13PM -0500, Charles Lepple wrote:
> 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.

3) Start with whatever you have and if a newbie points out some
difficulty, don't call him moron and fix it in the doc instead. Plus
motivate the newbies to be as much querulant as possible.

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