[OpenLayers-Dev] Additional Documentation

[Erik Uzureau]

Wow, great email -- I would have tapped in with paul in the "gosh, why don't
we just do it via wiki" camp
but this is a definite closer here... I hadn't thought of any of those
issues (except 7) and you detail them
very well here.

SVN it is! +1

e

On Thu, Nov 13, 2008 at 8:01 AM, Christopher Schmidt <
crschmidt at metacarta.com> wrote:

> 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
> _______________________________________________
> Dev mailing list
> Dev at openlayers.org
> http://openlayers.org/mailman/listinfo/dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/openlayers-dev/attachments/20081113/78b32bcc/attachment.html