The Guide - again

[markd at macports.org]

>> I think the distinction between types of users for documentation is
>> problematic.
>
>Problematic in what way? Do you mean you think it would be 
>problematic to write the Guide to target different classes of users? 
>Or do you mean you think users will currently find it problematic to 
>identify which information in the Guide is applicable to them? I'm 
>finding the latter.

I was really thinking it is a problem to classify information as
"advanced" and "basic", and I avoided that in the guide.  So I didn't say
exactly what I was thinking.  The reason is that these days people with
little experience read some advenced stuff on the internet and want to do
those things right away.  But targeting groups of users is different, and
I think necessary, so I misspoke.

As far as users having difficulty finding which information is applicable,
that may be so.  To be honest, I think the 1st phase of writing the Guide
(from scratch to feature complete summer - I hope) was/is mostly an
exercise in knowledge management.  After that phase is complete I think it
would make sense to think about users, how the material is presented
and/or formatted, and whether to split it or create supplements to it, and
anything else that makes sense.  I think various types of users finding
what they want is an important part of usability, but I've not had time to
think about that too much, and I'd be interested in hearing other opinions
too.
>
>
>Here's how I see the Guide at this time w.r.t. what kind of person 
>should read that section:
>
>1. Introduction -- all users
>2. Installing MacPorts -- all users
>3. Using MacPorts -- all users
>4. Portfile Development -- port maintainers
>5. Portfile Reference -- port maintainers, except that regular users 
>might well want to know about the different phases that MacPorts goes 
>through to install a port; or that ports can have dependencies and 
>what MacPorts does about that (i.e. it works out and installs the 
>dependencies first in the correct order); or that ports can have 
>startupitems and how that works
>6. MacPorts Internals
>        6.1. File Hierarchy -- all users
>        6.2. Configuration Files -- advanced users
>        6.3. Port Images -- all users
>        6.4. APIs and Libs -- developers of GUI clients
>        6.5. The MacPorts Registry -- base developers
>7. MacPorts Project -- all users
>8. MacPorts Guide Terms
>        Glossary -- no users (doesn't actually define any terms)
>
Yeah I think that pretty much describes the user/information mapping as it
is.  Though it is all subject to change as time goes on, what do you think
of the overall structure right now?  I would be interested to know your
opinion.  As I said before, it could be that the "internals" section ought
to be in another document.  But I'm not sure what it would be.  I just
looked at the FreeBSD Porter's Handbook, and it has a "Quick Porting" and
"Slow Porting" section.  That's interesting and doesn't get into "basic"
and "advanced" categories.

Mark