The Guide - again

[markd at macports.org]

>> 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
>
>So DITA is a OASIS-approved standard originating with IBM
>for doing documentation? Is there any reason to handle this
>with IBM-style complexity?

If we wish to do topic-based authoring.  If not, no.  But I hear people
asking for various conflicting rearrangements to the docs, so I made a
suggestion for how many types of docs could be generated from the same
data.
>
>>>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 don't think that macports committers would handle guide changes
>that mindlessly.

I do, and that is no insult to anyone.  The guide is not a repository for
just anything.  I personally don't think that one document is all we need.
 I never thought the guide should be the only document we'd ever have, and
I think the tendency is to assume with no real thoughts that it is the
only one we need.

>So in my opinion this process of doc writing should not become
>a closed thing. It is a bit, because of the tools in place, but we
>should not go and even embrace that closedness.
>
>> 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.
>
>No offense, but that sounds quite unefficient. I mean I find it great that
>you offer to do all this work. But if much of it can be avoided, than
>that should probably happen. There are tools where you can avoid
>drafting in plain text and then go into the "documentation IDE" to
>"implement" it.

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

It sounds inefficient because you're conflating contributing to the guide
and making minor edits.  The guide is a rewrite almost completely from
scratch.  And the parts that I'll contribute to "complete" it this summer
will be from scratch rewrites as well.  I gather all information from
wherever it exists currently and reorganize it, define terms where
necessary, and try to make it as coherent as possible.  Others were trying
to incrementally edit the old docs which sucked bad into a new doc which
didn't suck, and that would never work in my opinion.

Typing or editing is the trivial part.  It seems to me you see writing the
guide as a series of incremental edits, but it isn't.  And incremental
edits just aren't that hard to do in XML.  I am not a coder and I use an
editor and get along fine, and I learned it in two weeks so I could do
projects like this.

Mark