[mapserver-dev] github and Mapserver documentation

[Alan Boudreault]

I agree with Optiopn b).

Thanks,
Alan

On 12-11-02 05: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


-- 
Alan Boudreault
http://www.mapgears.com/