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

[DelazJ]

Hi all,

Le ven. 18 oct. 2019 à 09:14, matteo <matteo.ghetta at gmail.com> a écrit :

> Hi all,
>
> while reading the data and interpreting the results, what I found is
> that basically our official docs are not the firsts choice. People are
> mostly used to write something on google (or whatever) and get an
> answer.


Why? Because it's easier to do a web search for an item than browsing a
document. This is true for QGIS but applies to any other software. You do a
web search and then pick among what are returned (first! because you assume
they are the most relevant). And this is where we are failing. Responders
point that: our docs are not returned efficiently. Basically, do a search
for "QGIS expression": the first results are far from being the latest
version; you got 2.18, 2.14, 2.8 docs depending on the web search you use
(I tried duckduckgo, google, qwant). This is a known issue [0], an issue
being "fixed" [1] (there's still a lot to do: we should ensure our latest
docs is best served in web search engine - there are elements in the report
I mentioned earlier for anyone willing to help there)
The other part of the issue is, for those who know that there's an official
document, our search engine is failing or not as efficient as it should be.
Also a known issue [2][3]

There are other reasons:
* docs not clearly explaining the feature: sometimes it's because we don't
know (an almost empty PR - ref Nyall's comment on the changelog) and fail
to have someone explain to us what the feature exactly does
* docs not always up to date
* docs not well written (yep! we are not all professional writers and we
need to improve)
* ...
BUT if you first don't find the docs and then the feature, there's a little
chance you use it. So ensuring our docs are useful is not only about
writing features, it's first about visibility and fixing visibility issues
rely on developers skills. Yes, the docs need devs skill to fix inherent
issues. And sorry to say but I sometimes feel like there's a lack of
cohesion between the "teams" in the community and I'm personally fed up
with constantly **begging** help for these kinds of issues (see eg feedback
[4] to take a recent call).

[0] https://github.com/qgis/QGIS-Documentation/issues/3452
[1] https://github.com/qgis/QGIS-Documentation/pull/4274
[2] https://github.com/qgis/QGIS-Website/issues/156
[3] https://github.com/qgis/QGIS-Documentation/issues/2059
[4]
http://qgis-community-team.2324516.n4.nabble.com/Qgis-community-team-Documentation-wish-list-for-quot-hackfesters-quot-td3069.html

Regards,
Harrissou

Our (super beautiful docs) are more something to read slowly,
> study and make yours.
>
> The doc team did and is still doing an incredible work but we are
> relying on too few people.
>
> After discussing in these months with the doc team, psc, osgeo people,
> etc.. my conclusions are:
>
> * we have a complex framework with a steep learning curve for all the
> newcomers. Even if we wrote the guidelines, Alexandre made videos and
> people are helping other ones, we have spot PR of newcomers. BTW: I love
> our framework and wouldn't change it
>
> * even if we become more "soft" while reviewing PR (and with the "new"
> github system to directly accept reviewer's suggestions) I see new
> people scared by this system
>
> * the Postgres like manual is an idea, but we also should admit that
> postgres is a CLI software, QGIS has a lot of (beautiful) UIs
>
> Some times ago I tried to find a WYSIWYG system connected to git but
> couldn't find any suitable solution. I imagined something: the user logs
> it, adds/corrects/whatever something, before publishing the reviewers
> can approve it and we still have the history. IMHO such a system can
> attract more people CONTINUOUSLY to help us.
>
> Cheers and thanks for the discussion
>
> Matteo
> _______________________________________________
> 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/20191018/62dcfdc7/attachment.html>