The Guide - again

[C. Florian Ebeling]

>>> 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 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?


> 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.

To me it would appear sensible to try to pull in more people into this
endeavor. Otherwise you as a single final editor may easily become
over capacity.
One thing that might help with this would be to define "complete" for
the guide?



>>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 don't think that macports committers would handle guide changes
that mindlessly.

And also there is this other pattern, at wikipedia and other places with
the similar problem: some "expert" types throw in reliable content
using sluggish markup, only to give room to "editors" who bring the
detailed content into shiny shape. We could aim at something similar
as well and see how good that works.

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.

Florian


-- 
Florian Ebeling
Twitter: febeling
florian.ebeling at gmail.com