[OpenLayers-Dev] Proposition for a structured documentation

[Yves Jacolin (free)]

Hi dev,

Sorry to not answer before, I was busy. I would like to add few comments :)

Le lundi 24 novembre 2008, Christopher Schmidt a écrit :
> 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?)
Well, I don't think so. Documentation is (almost) as important as the code and 
we need to think for both how to structure it before to write something. At 
the FOSS4G 2008 you tell me that the wiki is unstructured (that's true) and 
you would like to move it on something more structured way. Copy-Past to svn 
won't change its structure. Why organize what we don't have? Because it is 
easier to organize something before than after: do you prefer organizing your 
code before or after writing it? ;)

And I agree with Tim Schaub about the possibility to share chapter between 
several contributor.

> 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.
This makes sence, I agree with it.

> 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.
It was what I mean by juste allow people to write some thing in the wiki and 
when it appears to be interesting to move on the svn (i.e. finalized), move 
on.

> 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.
see above, I agreed completly.

> > 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,
Ok I begin !

Y.
-- 
Yves Jacolin
-------------
"Donner la liberté aux individus ne suffit pas, il faut aussi leur donner du
pouvoir, de la puissance d'agir." M Gauchet

"Give freedom to people is not enough, we also have to give them the power 
to use this freedom, to act". M Gauchet
-------------
http://yjacolin.gloobe.org
http://softlibre.gloobe.org