[Qgis-psc] Documentation

[matteo]

Hi all,

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

+1
>  
> 
>     * 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

I think we should admit that despite the ultra huge efforts of the
writers we have not the power to have docs updated with code, for a lot
of different reasons:

* dev # >>> writers
* sorry devs, but **sometimes** the PR descriptions is cryptic
* doc framework not easy for new contributors (this complexity leads
often to have only spot contributions)

therefore we should (maybe) change the doc vision. The suggestion of
Paolo and Tim to have only a skeleton of docs that points to the
description (as we have right now in the UI and that I really like and
think is super useful) + user comments/links(videos/whatever (in a i18n
framework) is maybe a solution.

Besides that, I also think that something has to be made on dev side:

* opengis.ch grant proposal should automate some process
* given that we push more to have PR than direct commits, a PR without
**at least** a doc skeleton that a writer can copy/paste cannot be merged

Other processes can be automated, but maybe this is the way to go

Cheers

Matteo