[OpenLayers-Dev] Proposition for a structured documentation

[Tim Schaub]

Hey-

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

Tim

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


-- 
Tim Schaub
OpenGeo - http://opengeo.org
Expert service straight from the developers.