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 < [EMAIL PROTECTED]> 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@openlayers.org > http://openlayers.org/mailman/listinfo/dev >
_______________________________________________ Dev mailing list Dev@openlayers.org http://openlayers.org/mailman/listinfo/dev
