[OpenLayers-Dev] Additional Documentation

[Christopher Schmidt]

On Thu, Nov 13, 2008 at 08:16:24AM -0500, Paul Spencer wrote:
> Chris ... can you explain why you would want to do it this way rather  
> than through the wiki?  I am for this approach but it seems that there  
> is already some level of prose documentation in the wiki and having  
> stuff in two places seems a bit confusing.

Wikis have a number of things that make me not prefer them for
management of content like documentation. 
 
 1. Wikis do not easily correlate to SVN history: Things like tagging,
    branching, etc. are not a built in part of the way that wikis work,
    which (for documentation which changes with releases) is at best
    unfortunate, but at worst can be downright useless. The spherical
    mercator doc, for example, will probably be very different for the
    3.x series compared 2.x, and SVN gives us an easy way to manage 
    docs along with code as far as per-version docs go.
 
 2. Wikis are difficult to edit in the text editor of your choice. 
    Trac is especially troubled by this, since it's not all that great
    of a wiki to begin with: no section-specific editing, for example.
    However, no matter what, managing large blocks of text is (imho)
    easier in a text editor than in a browser.
 
 3. Poorly suited for offline distribution: It's hard to take wikitext
    and turn it into something that you can 'ship' in another form, 
    because wikis tend to be fixed in their database format, and not
    verey good with input/output APIs.
 
 4. A social, rather than technical, limitation is the fact that wikis
    tend to encourage the "I'll write some of it now, and someone else
    will finish it off later" incompleteness. With documentation which
    is published in non-wiki form, I think there is a larger social
    pressure to do it "right" -- in the same way that we want our
    high-quality code to be managed by people who are going to take the
    effort to make the code work right, I think that we want this to be
    true for our high quality documentation.

 5. As Yves pointed out, the tools for managing translation-type efforts
    with regard to SVN are somewhat simpler: the SVN "universal
    monotonically increasing identifier" lets you easily say "Okay, when
    was this last updated vs. when the translation was last updated".

 6. To some extent, it's harder to customize the look and feel of wiki
    documentation -- code syntax highlighting, for example, is harder to
    pull together. 

 7. Some forms of prose documentation -- like the OpenGeo OpenLayers
    workshop -- will never be something that you can shove into a wiki
    form: http://workshops.opengeo.org/openlayers/intro/doc/
    The paging, etc. are just not fit for a wiki, and as we get more
    documentatino like this, I expect it will become more and more true.

Essentially, the wiki  -- like the FAQ -- is a great scratchpad, that
allows many people to collaborate together on information about a
particular feature, or question, or what not. However, when you actually
want a published doc -- think something that could be published in the
"OpenLayers book" that so many people are asking me to write ;) -- you
want *one* editor or a team of dedicated editors to take that mish-mash
of content, and turn it into a coherent piece of text that non-wizards
can understand, and I simply don't think a wiki is the best place for
that. 

Does that explain my thoughts to a certain extent? Certainly, some of
these technical problems are possibly solvable with more work --
ikiwiki, for example, is an SVN-backed wiki that wouldn't be a horrible
place to start for SVN-backed documentation managed through a wiki --
but it seems to me that the existing trac wiki is never going to be the
best source of documentation infrastructure.

For the record, I see this as being somewhat similar to the
Plone/MapServer situation, where Jeff and Howard are trying to move away
from managing the docs thrugh Plone and instead manage thrugh SVN. In
theory, managing through Plone offered great benefits for allowing the
community to contribute -- but in practice, it's just a pain in the
keyster. 

Regards,
-- 
Christopher Schmidt
MetaCarta