[Qgis-psc] Documentation

[DelazJ]

Hi Paolo, all

Le mer. 13 nov. 2019 à 19:26, Paolo Cavallini <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 ?
Anyways, I agree. Time to act.


> * 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)?

(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.

* 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".

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.
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...


> 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.

Best wishes,
Harrissou

All best wishes.
> --
> Paolo Cavallini - www.faunalia.eu
> QGIS.ORG Chair:
> http://planet.qgis.org/planet/user/28/tag/qgis%20board/
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-psc
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20191115/544496db/attachment.html>