[Qgis-psc] Documentation

[Alessandro Pasotti]

On Tue, Nov 19, 2019 at 10:02 AM matteo <matteo.ghetta at gmail.com> wrote:

> 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
>
>
Agreed, but with the following obvious exception: when a developer is
willing to write the documentation him(her)self.

Please don't add another automatic PR blocker here that would slow down our
normal workflow, Travis and peer-reviews are more than enough.

Cheers

-- 
Alessandro Pasotti
w3:   www.itopen.it
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20191119/14848398/attachment.html>