The Guide - again

[markd at macports.org]

>Message: 5
>Date: Sat, 07 Mar 2009 21:33:20 +0100
>From: Rainer M?ller <raimue at macports.org>
>Subject: Re: The Guide - again
>To: Ryan Schmidt <ryandesign at macports.org>
>Cc: MacPorts Development <macports-dev at lists.macosforge.org>
>Message-ID: <49B2DA10.8050008 at macports.org>
>Content-Type: text/plain; charset=ISO-8859-1
>
>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.  But chunking documents into "topics" and assembling them
into various docs as needed would at least allow it in theory.  It is
called DITA.  Another XML standard.  I know, ugh.  But I just don't see
how we can ditch XML and still do what we need to do. 
http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

But the guide is not complete yet.  This summer I intend to make a final
push to do it.  Of course it will never be finished, but the big missing
pieces can be filled in, and then sourcing the man pages out of it can
happen.
>
>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.

As Ryan mentioned, there is the chunked version.  It could be that the
internals section and the project section doesn't belong, and I think
after finishing the major parts this summer we could discuss that as a
"where do we want our docs to go now" discussion.
>
>> 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?

But if we have more than a few people contributing anything other than
incremental changes, we'd need to use the formal approval process we've
already talked about.  So I don't see how that solves anything.  There is
a natural tendency  for people to throw all kinds of stuff into documents
just because they can.  I use text files in Textedit to flesh out
documents and document structure so I don't understand why this is not
acceptable to do this or any other technique and post it for review. 
Contributions don't need to be in XML.

Mark