Wow, great email -- I would have tapped in with paul in the "gosh, why don't we just do it via wiki" camp<br>but this is a definite closer here... I hadn't thought of any of those issues (except 7) and you detail them <br>
very well here. <br><br>SVN it is! +1<br><br>e<br><br><div class="gmail_quote">On Thu, Nov 13, 2008 at 8:01 AM, Christopher Schmidt <span dir="ltr"><<a href="mailto:crschmidt@metacarta.com">crschmidt@metacarta.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="Ih2E3d">On Thu, Nov 13, 2008 at 08:16:24AM -0500, Paul Spencer wrote:<br>
> Chris ... can you explain why you would want to do it this way rather<br>
> than through the wiki? I am for this approach but it seems that there<br>
> is already some level of prose documentation in the wiki and having<br>
> stuff in two places seems a bit confusing.<br>
<br>
</div>Wikis have a number of things that make me not prefer them for<br>
management of content like documentation.<br>
<br>
1. Wikis do not easily correlate to SVN history: Things like tagging,<br>
branching, etc. are not a built in part of the way that wikis work,<br>
which (for documentation which changes with releases) is at best<br>
unfortunate, but at worst can be downright useless. The spherical<br>
mercator doc, for example, will probably be very different for the<br>
3.x series compared 2.x, and SVN gives us an easy way to manage<br>
docs along with code as far as per-version docs go.<br>
<br>
2. Wikis are difficult to edit in the text editor of your choice.<br>
Trac is especially troubled by this, since it's not all that great<br>
of a wiki to begin with: no section-specific editing, for example.<br>
However, no matter what, managing large blocks of text is (imho)<br>
easier in a text editor than in a browser.<br>
<br>
3. Poorly suited for offline distribution: It's hard to take wikitext<br>
and turn it into something that you can 'ship' in another form,<br>
because wikis tend to be fixed in their database format, and not<br>
verey good with input/output APIs.<br>
<br>
4. A social, rather than technical, limitation is the fact that wikis<br>
tend to encourage the "I'll write some of it now, and someone else<br>
will finish it off later" incompleteness. With documentation which<br>
is published in non-wiki form, I think there is a larger social<br>
pressure to do it "right" -- in the same way that we want our<br>
high-quality code to be managed by people who are going to take the<br>
effort to make the code work right, I think that we want this to be<br>
true for our high quality documentation.<br>
<br>
5. As Yves pointed out, the tools for managing translation-type efforts<br>
with regard to SVN are somewhat simpler: the SVN "universal<br>
monotonically increasing identifier" lets you easily say "Okay, when<br>
was this last updated vs. when the translation was last updated".<br>
<br>
6. To some extent, it's harder to customize the look and feel of wiki<br>
documentation -- code syntax highlighting, for example, is harder to<br>
pull together.<br>
<br>
7. Some forms of prose documentation -- like the OpenGeo OpenLayers<br>
workshop -- will never be something that you can shove into a wiki<br>
form: <a href="http://workshops.opengeo.org/openlayers/intro/doc/" target="_blank">http://workshops.opengeo.org/openlayers/intro/doc/</a><br>
The paging, etc. are just not fit for a wiki, and as we get more<br>
documentatino like this, I expect it will become more and more true.<br>
<br>
Essentially, the wiki -- like the FAQ -- is a great scratchpad, that<br>
allows many people to collaborate together on information about a<br>
particular feature, or question, or what not. However, when you actually<br>
want a published doc -- think something that could be published in the<br>
"OpenLayers book" that so many people are asking me to write ;) -- you<br>
want *one* editor or a team of dedicated editors to take that mish-mash<br>
of content, and turn it into a coherent piece of text that non-wizards<br>
can understand, and I simply don't think a wiki is the best place for<br>
that.<br>
<br>
Does that explain my thoughts to a certain extent? Certainly, some of<br>
these technical problems are possibly solvable with more work --<br>
ikiwiki, for example, is an SVN-backed wiki that wouldn't be a horrible<br>
place to start for SVN-backed documentation managed through a wiki --<br>
but it seems to me that the existing trac wiki is never going to be the<br>
best source of documentation infrastructure.<br>
<br>
For the record, I see this as being somewhat similar to the<br>
Plone/MapServer situation, where Jeff and Howard are trying to move away<br>
from managing the docs thrugh Plone and instead manage thrugh SVN. In<br>
theory, managing through Plone offered great benefits for allowing the<br>
community to contribute -- but in practice, it's just a pain in the<br>
keyster.<br>
<br>
Regards,<br>
<font color="#888888">--<br>
Christopher Schmidt<br>
MetaCarta<br>
</font><div><div></div><div class="Wj3C7c">_______________________________________________<br>
Dev mailing list<br>
<a href="mailto:Dev@openlayers.org">Dev@openlayers.org</a><br>
<a href="http://openlayers.org/mailman/listinfo/dev" target="_blank">http://openlayers.org/mailman/listinfo/dev</a><br>
</div></div></blockquote></div><br>