[Qgis-community-team] [Qgis-user] [Qgis-psc] User question of the month

[Alexandre Neto]

Hi Paolo,

Maybe I misread the PSC ideas, appologies for that.

Some random ideas for something in between what we have, and google docs
documentation:
  - Start doing a call for documentation (maybe focused on the user manual)
to help finish the work before the release of each LTR (February 2020 for
3.10). In it, we can:
     1. Point them to the list of active issues.
     2. Point them to the writing docs guidelines and videos about how to
do it.
     3. Suggest them to contribute with content by writing it in the actual
github issues, describing the proposed text and where it should go in the
docs. In issues, they can use markdown and add images.
- Let the experienced sphinx gurus (those highlighted being) convert that
into sphinx and integrate in the docs.
- If needed, use the available funds (if any) to hire someone (it can be a
non-gis person) to "sphinxify" the contents.
- Ask/request/demand that Developers provide more information about the new
features they produced. Maybe another check mark in the PR check list?
- Hire a professional Tech Writer to analyze and propose changes to the
current organization of the Docs, focused on making it easier to maintain.

On the Docs team side (don't worry we are all on the same side here), we
can:
- *Try* to make the guideline simpler with less mandatory components; (we
no longer request that images are in a particular distribution)
- *Try* to narrow down the "fancy" sphinx directives that make
understanding the content harder for a beginner (for example stop using the
:guilabels and stick to bolds and italics?
- *Try* to do reviews ASAP and without requiring too much from the effort
from the contributor (Harrissou and Havart are being quite fast theses
days, thank you)
- Maybe in some cases, if the contributor does not mind (I don't), let a
core contributor simply edit the PR and fix the errors or problems for the
user. This may make his experience better than requesting too many changes.

There is also some work we have been talking about for a long time, that I
think that can make things easier for new comers, move static content
(stuff that don't change in each version) from the QGIS-Documentation
repository into the QGIS Website. Example: Documentation guidelines, the
developer guide, maybe even the Gentle Introduction to GIS.

Thanks,

Alexandre Neto

On Thu, Oct 17, 2019 at 6:55 AM Paolo Cavallini <cavallini at faunalia.it>
wrote:

> Hi Alexandre,
>
> On 17/10/19 01:46, Alexandre Neto wrote:
>
> > I must say I am quite disappointed. I would expect more support from the
> > PSC, not less...
>
> sorry if we gave this impression. we deeply appreciate all the wonderful
> work you and others have done on the documentation.
> our considerations stem simply for the hard fact that despite all the
> efforts, the budget set out for this, and the goodwill, we are not able
> to maintain a full up to date documentation.
> as I wrote earlier, the only way I see to change this would be to hire
> several full time professional writers, which is far beyond our budget.
> do you see a different way to solve this?
>
> > I am not sure the bottleneck is the documentation structure complexity.
> > It's just not a sexy work. Like testing... People don't even like to
> > discuss it.
> >
> > From previous talks with the "docs team" we all agreed that moving away
> > from sphinx would be a bad move.
> >
> > I don't think many people will join the documentation effort just
> > because we moved to markdown or google docs. If they do, they probably
> > won't stick around for long (my personal feeling), and who ever is left
> > will have an harder task to keep the docs updated.
> >
> > Unless we skip versioning all together, we still need pull requests,
> > commits, conflict resolution... which is, IMHO is the worst part for new
> > comers.
> >
> > BTW, sphinx can use markdown as an input format, it renders quite well
> > in github, but you lose most of the benefits of using RST.
> fully agreed on all the above.
>
> Cheers.
> --
> Paolo Cavallini - www.faunalia.eu
> QGIS.ORG Chair:
> http://planet.qgis.org/planet/user/28/tag/qgis%20board/
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20191017/d3f645c5/attachment.html>