[OpenLayers-Dev] Proposition for a structured documentation

[Christopher Schmidt]

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.
> 
> http://trac.openlayers.org/wiki/proposDoc

Yves,

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 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
shape.

> 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.

Regards,
-- 
Christopher Schmidt
MetaCarta