[mapserver-dev] github and Mapserver documentation

[Lime, Steve D (DNR)]

Agreed, option b... We (or at least I) have tried transitioning the same ticket to a documentation state over the years with mixed results.

-----Original Message-----
From: mapserver-dev-bounces at lists.osgeo.org [mailto:mapserver-dev-bounces at lists.osgeo.org] On Behalf Of Daniel Morissette
Sent: Friday, November 02, 2012 9:21 AM
To: mapserver-dev at lists.osgeo.org
Subject: Re: [mapserver-dev] github and Mapserver documentation

I'd also opt for option b) creating new issues for docs with a reference to the original ticket which can then be marked as closed.



On 12-11-02 8:11 AM, Jeff McKenna wrote:
> Hello Håvard,
>
> I would agree with your thoughts.
>
> As in the past documentation systems, I prefer separate documentation
> tickets be created.  Most long-time MapServer devs are very good at
> doing this, but it is a good time now to remind everyone to do so, and
> choose a related "Docs" label.
>
> Also, I'd like to thank you personally for your recent contributions. I
> know git/github is challenging, and I thank you for wading through all this.
>
> -jeff
>
>
>
> On 12-11-02 6:33 AM, Havard Tveite wrote:
>> Dear developers,
>>
>> There are now quite a number of issues (opened and closed)
>> on Mapserver github.  In my opinion, this means that
>> measures should be taken to simplify searching for open
>> issues.
>> As an occasional contributor to documentation I have not
>> gotten used to github, and have found it more cumbersome
>> to work with compared to the old system.
>> Some things that has to do with Mapserver documentation
>> and github:
>>
>> 1) Spurred by a message on the mapserver users list, some
>> days ago I had a look at issues on github.  I discovered
>> some enhancement issues that had been closed, but where
>> the enhancements had not been documented.
>>
>> I think it is important that all Mapserver features are
>> documented in the official docs.  I therefore urge
>> developers to keep documentation in mind.
>>
>> 2) It is difficult to find issues that are left open due
>> to missing documentation.  github provides some mechanisms,
>> but I don't know about all of them or how to best utilise
>> them.
>>
>> Two options (there are probably more):
>>
>> a) Issues can be given documentation tags in addition to
>> "feature" tags, and a tag on an open issue indicates that
>> that something needs to be done related to that tag.
>> When one task is completed, the corresponding tags should
>> be removed, but the issue left open until all tasks have
>> been completed (and all tags removed).
>> Since this means that issue metadata will be removed, it
>> will make it more difficult to navigate the issues on
>> github.
>>
>> b) Separate issues are created for documentation.
>> When the coding is finalised, the original issue can be
>> closed, and documentation issues opened for the relevant
>> documentation (core, mapscript, ...).
>> This means some more work for the developers, and also
>> seems kind of strange, since many would argue that coding
>> and documentation belongs together.
>>
>> For github I prefer option b), as that will make it easier
>> to navigate among the issues (both open and closed ones).
>>
>> 3) For the benefit of searching, all new issues should get
>> tagged.
>> It would have been great if the creator of an issue also
>> could do the initial tagging.  As far as I know, this is not
>> possible if the reporter / creator does not have sufficient
>> github rights.
>> In the current situation, I think that new issues must be
>> tagged by a developer with sufficient rights.
>>
>> 4) Issues that are finalised should be closed as soon as
>> possible.
>> This is a problem when the only thing left is the
>> documentation, since documentation lives in a different
>> github "tree", and those working on documentation do not
>> necessarily have sufficient rights in the github mapserver
>> "tree" to close issues there.
>>
>> Should we consider moving documentation issues to the doc
>> "tree" on github?
>>
>>
>> Håvard
>
>


-- 
Daniel Morissette
http://www.mapgears.com/
Provider of Professional MapServer Support since 2000

_______________________________________________
mapserver-dev mailing list
mapserver-dev at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/mapserver-dev