[mapserver-dev] docs and branches...

[Jeff McKenna]

I think we've now had 2 big doc discussions on IRC lately, but I suggest 
we move those discussions to this thread so we can all have input.

I am for tagging and publishing the docs, but only as long as those docs 
are frozen (no more updates ever), and somehow those older doc versions 
can't be mistakenly referenced by Google or whatever (I remember this 
was a big problem with the doc versions with the blue site, users 
thinking the latest mapfile parameters were in the doc they were 
viewing, but they were accessing 3.0 docs or something.  The result was 
that power users of the old blue site always went to the dev versions of 
the docs.

Can we somehow handle these issues?

-jeff




Paul Ramsey wrote:
> I think the whole tree should be branched/tagged, docs and code, IMO. 
> The branched docs might not get much work on them, but at least there is 
> the option, should a serious documentation mistake arise.
> 
> P.
> 
> On Jan 21, 2009, at 10:15 AM, Frank Warmerdam wrote:
> 
>> Daniel Morissette wrote:
>>> Steve Lime wrote:
>>>> Hi all: What are the plans for the docs relative to branching. Are 
>>>> we going to branch the
>>>> docs or just maintain things in the trunk? I think this matters for 
>>>> setting up a mapserver_docs
>>>> svn access group.
>>>>
>>> I'd lean towards branching docs for every release, but my 
>>> understanding from our IRC meeting on docs a few weeks ago was that 
>>> the majority saw no point in branching docs and wanted to have a 
>>> single set of docs always living in trunk.
>>> We should probably wait to hear back from Jeff on this but I think 
>>> he'll be back only at the end of the week.
>>
>> Daniel,
>>
>> I took a different impression away from that meeting.  I understood we
>> would be branching and tagging docs along with the source code and that
>> a packaged copy of html and pdf docs would be available for download on
>> the download site with major releases.
>>
>> Also that on the web site we would eventually offer html docs for older
>> versions though the primary web site view would be the "trunk" docs.
>> Also that the trunk docs would attempt to describe when new features
>> were added so that folks using older versions would have some sense of
>> whether the feature applies to their version or not.  I'm a bit unclear
>> on how far this will be taken.
>>
>> Best regards,
>> --