[Qgis-psc] Documentation

[Paolo Cavallini]

Thanks Harissou for your comments

Il 15/11/19 16:53, DelazJ ha scritto:

> Le mer. 13 nov. 2019 à 19:26, Paolo Cavallini <cavallini at faunalia.it
> <mailto:cavallini at faunalia.it>> a écrit :
> 
>     Hi all,
>     we had a lengthy and I think fruitful discussion about the future of
>     documentation. I think time is ripe to take steps towards a concrete
>     solution.
> 
>     AFAICT, a reasonable proposal stemming out of the discussion was:
> 
> 
> Do you refer to a recent PSC meeting (I can't find last meetings notes
> in the wiki btw) or to these last months discussions in the different
> mailing-lists ?

the discussions in the mailing lists

> Anyways, I agree. Time to act.

great

>     * having a core documentation, listing all functions available with at
>     least a minimal description
> 
>  
>  Is that something different from our current manuals? I mean, are there
> things in the current docs that would not have their place in the future
> docs, following this scenario? And what kind of contents would/could be
> added (other than the media you mention later)?

it's different in the sense that we might stop trying to give
comprehensive description for every function, but rather to make sure
there is at least a short description for each, aiming therefore to
completedness rather than for comprehensiveness.
I'm not suggesting to throw away what we have, of course (even though it
might make sense to move it to the notes)

>     (this could be taken from the commit
>     description for the upcoming features, and the version number where it
>     first appeared can be added)
> 
>  
> https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty
> represents the issue reports with NO description (because there was none
> in the commit). Add to that the issue reports whose description is only
> the commit title. Morality: writers still have to browse qgis/QGIS
> repository (or wait for the changelog to have more resources to pick
> from). So imho there's a work to do on the devs side to get them used to
> descriptive and easily understandable commits or PR.

agreed: we can require a minimal description for a PR to be accepted

>     * allow comments by all interested parties on each function, to
>     encourage the addition of heterogeneous material, e.g. links to videos,
>     presentations, and more
> 
>  
> Do we have an example of what that could look like and how this is
> managed? Or is this something we'd "invent"? I must confess that I fail
> to see the "end product".

the idea was proposed by Tim, inspired by the PostgreSQL manual with
user comments
of course our situation is rather different, being an end user, desktop
software, but I think you got the idea

>     UNclear how to handle translations:
>     * stick to English, and let people adding translations as comments
>     as above
>     * starting with a multilingual structure from the beginning.
>     I think we agree that we want to keep a revision-controlled system, so
>     the main issue would be to have a web interface displaying each function
>     as a page, and allowing comments.
> 
> 
> Being a non-native English speaker and surrounded by people who do not
> speak English and love QGIS, I'd definitely prefer QGIS provides a way
> to get translation. Having materials in your language also contributes
> to QGIS adoption.

agreed

> There is(was?) a Transifex web feature that allows, from what I
> understood at that time, to translate directly in the published docs.
> Never looked at it but maybe someone...

if we use the current approach, the string will be translatable as usual

>     Of course there are other views, and nothing has been decided yet, so
>     alternative proposals are most welcome.
> 
>  
> Maybe it's because I do not yet see what the proposals above would
> output, but I miss an information: what issue(s) are these changes
> trying to fix: the lack of contributors to docs, too many resources on
> personal blogs, docs not targetting the users need (ex of how-to
> suggestion), outdated information in docs, docs not being enough
> descriptive/detailed, docs being hard to contribute to, docs being hard
> to maintain/build, docs not being sexy, attracting more educational
> world contributors, prioritizing docs, no advertising on official
> docs... ? Cameron's thread as well as the user survey pointed many
> (different) levels of issues and since in my case I don't know which
> ones the PSC wants to prioritize, I'm pretty lost.
> I think that without knowing what we want to fix/improve here, it's hard
> to come with comparable alternatives, if any. My 2cts.

The aim is twofold:
* to have a timely, feature complete documentation, that we are able to
maintain with out current resources
* act as central repository of the myriads of documents in disparate
formats scattered everywhere; the system may encourage documentation
writer to add their content there to enjoy increased visibility, without
the associated high costs of bringing everything to a common format.
I must stress that nothing has been decided yet: this is a proposal,
better ones are welcome. What  believe it's important is to move forward.
Cheers.
-- 
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/