The Guide - again

[Ryan Schmidt]

On Mar 8, 2009, at 00:59, markd at macports.org wrote:

>> Ryan Schmidt wrote:
>>> I do not believe that we need to separate these into different
>>> documents because there is overlap between these different peoples'
>>> needs. We could do a better job of indicating which sections are for
>>> which audience, or rearranging sections in the guide to group things
>>> by audience.
>
> Hi Ranier,
>
> 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.

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)