[OpenLayers-Dev] Proposition for a structured documentation
tschaub at opengeo.org
Mon Nov 24 15:40:23 EST 2008
Christopher Schmidt wrote:
> On Mon, Nov 24, 2008 at 08:36:40PM +0100, Yves Jacolin (free) wrote:
>> Following the first steps Chris made few weeks ago, I would like to propose
>> some though about documentation. As wiki and svn documentation are
>> complementary, the first one will be a kind of quick write documentation. The
>> svn one will be more structured.
> My feeling on this is that the first step is to concentrate on getting
> the documentation written. Once we have the documentation written, it
> becomes a lot easier to organize it -- trying to do so ahead of time may
> be a bit premature. (Why organize what you don't yet have?)
I think there is a lot of sense in organizing ideas. Not that we would
commit ourselves to an outline for eternity, but it is nice to have a
sense of what you hope people to write before tasking them with writing.
I like the look of the "Official documentation" outline - though I would
resist getting really specific at this point. I think this is probably
what Chris is saying as well.
If there is other documentation out there that people find particularly
effective - preferably documentation for software of somewhat similar
scope - it would be good extract a general outline from that.
The nice thing about having some general agreement about the structure
of the docs would be that people could accept tasks for writing
> I would say that in general, it probably makes sense, as much as
> possible, to strive for a single set of reference documentation -- in
> the same way that a book would be organized. This means that "Howto"s
> seperate from other docs mya not make the most sense -- instead, these
> things should be slotted in where they fit. Also, rather than have
> seperate trees for different langauges, in my mind, we should just have
> the links to seperate language translations alongside english
> links, though how exactly to do that remains to be seen.
> Additionally, I don't think that we should plan on maintaining *any*
> long term documentation -- that is, documentation that we expect to
> maintain as the public face to users -- in the wiki. Instead, we should
> migrate this information into the 'official' documentatino as we see it
> is stable enough to be maintained, and keepin things up in the wiki
> should be discouraged.
> As we see more of the 'official documentation' take shape, we can see if
> I'm totally out of line, but personally, I think that the wiki should be
> for notes -- and that as we get things put together, we should build
> them into 'official' documentatino as soon as they've taken serious
>> I have some contents in french for the second part (first chapters) which I
>> can translate it in english (but realy need to be corrected by a native
>> english writer ;) ).
> I'm totally willing to do so. Let me know when you're far enough along
> that you're looking for feedback.
OpenGeo - http://opengeo.org
Expert service straight from the developers.
More information about the Dev