The Guide - again

[Rainer Müller]

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.

I don't like the fact that the guide is one huge document. We discussed
splitting the guide into single pages ('chunked' in docbook terms)
before, but the majority was against it. In my opinion it would at least
make sense to split the guide into pages each of them relevant for
users, maintainers, base hackers.

There is the MacPorts Internals documentation (API, registry etc.) which
is not interesting for anyone else than base hackers. Maybe it should
not be in the guide at all, but live in the repository as plain text only.

> I do not believe we need to move all or part of the guide to the  
> wiki. Quite the opposite: documentation that's getting created in the  
> wiki should get moved to the guide.

To be honest, editing the guide sucks. Contributing to the wiki is much
easier.

Especially if the concern is the guide being outdated, I see the problem
in the guide format. We had the recent discussion to move the guide to
another markup language but it was teared down. What else can we do to
attract more people for writing documentation?

Rainer