<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Nov 19, 2019 at 10:02 AM matteo <<a href="mailto:matteo.ghetta@gmail.com">matteo.ghetta@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi all,<br>
<br>
> Do you refer to a recent PSC meeting (I can't find last meetings notes<br>
> in the wiki btw) or to these last months discussions in the different<br>
> mailing-lists ?<br>
> Anyways, I agree. Time to act.<br>
<br>
+1<br>
>  <br>
> <br>
>     * having a core documentation, listing all functions available with at<br>
>     least a minimal description<br>
> <br>
>  <br>
>  Is that something different from our current manuals? I mean, are there<br>
> things in the current docs that would not have their place in the future<br>
> docs, following this scenario? And what kind of contents would/could be<br>
> added (other than the media you mention later)?<br>
> <br>
>     (this could be taken from the commit<br>
>     description for the upcoming features, and the version number where it<br>
>     first appeared can be added)<br>
> <br>
>  <br>
> <a href="https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty" rel="noreferrer" target="_blank">https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty</a><br>
> represents the issue reports with NO description (because there was none<br>
> in the commit). Add to that the issue reports whose description is only<br>
> the commit title. Morality: writers still have to browse qgis/QGIS<br>
> repository (or wait for the changelog to have more resources to pick<br>
> from). So imho there's a work to do on the devs side to get them used to<br>
> descriptive and easily understandable commits or PR.<br>
> <br>
>     * allow comments by all interested parties on each function, to<br>
>     encourage the addition of heterogeneous material, e.g. links to videos,<br>
>     presentations, and more<br>
<br>
I think we should admit that despite the ultra huge efforts of the<br>
writers we have not the power to have docs updated with code, for a lot<br>
of different reasons:<br>
<br>
* dev # >>> writers<br>
* sorry devs, but **sometimes** the PR descriptions is cryptic<br>
* doc framework not easy for new contributors (this complexity leads<br>
often to have only spot contributions)<br>
<br>
therefore we should (maybe) change the doc vision. The suggestion of<br>
Paolo and Tim to have only a skeleton of docs that points to the<br>
description (as we have right now in the UI and that I really like and<br>
think is super useful) + user comments/links(videos/whatever (in a i18n<br>
framework) is maybe a solution.<br>
<br>
Besides that, I also think that something has to be made on dev side:<br>
<br>
* <a href="http://opengis.ch" rel="noreferrer" target="_blank">opengis.ch</a> grant proposal should automate some process<br>
* given that we push more to have PR than direct commits, a PR without<br>
**at least** a doc skeleton that a writer can copy/paste cannot be merged<br>
<br></blockquote></div><div class="gmail_quote"><br></div><div class="gmail_quote">Agreed, but with the following obvious exception: when a developer is willing to write the documentation him(her)self.</div><div class="gmail_quote"><br></div><div class="gmail_quote"></div><div>Please don't add another automatic PR blocker here that would slow down our normal workflow, Travis and peer-reviews are more than enough.</div><div></div><div></div><div><br></div><div>Cheers</div><div><br></div><div>-- <br><div dir="ltr" class="gmail_signature">Alessandro Pasotti<br>w3:   <a href="http://www.itopen.it" target="_blank">www.itopen.it</a></div></div></div>