[Qgis-community-team] Help and manual

[Otto Dassau]

Hi,

Am Thu, 11 Jul 2013 11:10:37 +0200
schrieb Paolo Cavallini <cavallini at faunalia.it>:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Il 11/07/2013 11:02, Otto Dassau ha scritto:
> 
> > a) as you mentioned, the structure is different and maybe not well usable
> >    within a user manual
> 
> In principle I agree, in practice I checked a few pages of the manual, and
> I did not see them out of context as Help pages.
> 
> > b) the amount of "help" pages for hundreds of integrated application
> > modules is too much for the manual, which already has about 250 pages.
> 
> yes, I was suggesting to point only to the pages, as relevant for each
> dialog.
> 
> > Apart from that I like the current situation/idea, having the module help
> > directly integrated into a help tab for each module, rather than opening
> > another browser tab.
> 
> agreed; this would hold true also for all Help pages. 
> I think a more uniform approach would be preferable.

good idea. It could e.g also be an approach for the core plugins.  

> my main concern, however, is the maintainability of the whole structure:
> if I'm not wrong, the Help pages are currently out of sync with the app
> (and the manual). of course, a mixed approach is also good, pointing to
> manual pages where appropriate, and to specific Help pages when available.

ok, this might be a reason to integrate the help pages with the module
itself, as done in GRASS, so changes to the module can directly and easily be
applied to the help page by the developer as well. Is that what you mean and
would suggest?

This would exclude the help pages from the general documentation repository.
But if that approach would make sense, for example encourage more developers
to document their work, the help pages also might be linked into the docs
repository for translation, if the original structure fits. 

this is just an idea and kind of another story... but in fact it is common,
that documenters have problems to figure out all updates, new features and
functionality a tool provides (although many devs add a [FEATURE] remark to
their commits). It is usually time consuming, searching for the right
person, writing emails to the lists, asking questions, because it is unclear
who added/updated/extended what functionality to tool x and to find out how
it exactly works.

I would love to make the work of our documenters easier and I think this
process could be improved, if developers get a bit more involved providing
short but clear notes about the work they did. This is not very popular for
many devs, I know, but it would improve the manual a lot, if we could
integrate this fact into the documentation process.

Regards
Otto

> All the best.
> - -- 
> Paolo Cavallini - Faunalia