[Qgis-psc] Documentation work

Mon Jan 9 04:37:28 PST 2017

Hi,
To react on the initial subject, let me thank you, Andreas, for having
raised it. And as suggested by Tim, here are some inputs from me (*Bear
with me, I'd written a long and argumented message but I almost lost it
while switching devices before I sent it so this one is quickly rewritten
and less constructed and, maybe still long. Sorry*)...

This issue actually has been floating around in my head for a moment,
looking at all the great energy and enthusiasm put in the move to QGIS3 and
all the new issues those commits create in the Doc repo. QGIS 3 is going to
be a nicer application.
But I was a little bit disappointed to not see any discussion around
documentation. In the meantime, the Doc repo becomes a low-traffic one:
e.g., during the last month, 16 issues have been fixed while 27 new ones
were created [0]. In the last months, the mean of active contributors would
count on fingers of one hand, I think.
Browsing stats of the doc repo [1], we currently have:
* >120 issues for 3.0
* 72 for 2.16 and 2.18
* 40 without milestones, sometimes very old issues or global issues related
to the doc infrastructure/organisation itself.
A heavy task !

Yes, LTR releases should be the target of documentation. But we currently
do not know when the next LTR (3.2) will be available and until that
moment, I think that the majority of users will likely stick to a 2.x
version. Reason why I think a 2.18 doc should be released. I personally do
not consider 3.x issues yet when contributing to doc. It can be seen like
overloading the work given that some features in 2.x are broken/removed in
3.0 but other features are improvements of existing features and require
them to be prealably filled. So given that I don't have any idea of the
balance, I'm still focusing on 2.18. Maybe it's now time to have, like it
was done for QGIS, two branches in Doc repo (master_2/2.18 and
master/testing), so that available people can begin tackling some features
of QGIS3.

So, in any case, If we want a 3.2 doc to be released nearby QGIS3.2
release, we obviously need more people involved in QGIS Documentation and
also an idea of what we would like a QGIS3 documentation to look like.

**People involvment**

Involving people begins with a descriptive commit of the feature by QGIS
developers and by their availability when they are pinged by doc team for
more information. The first part seems to work well for most of the
developers and would surely be improved by the PR template [2].
Then any PR in QGIS-Doc repo should not be left without feedback for weeks
(though I know we are all contributing on a volunteer basis). We (englobing
all of us, given that you don't need to be a doc repo maintainer before
commenting) should ensure this reactivity. Lack of feedback slow down
people and can discourage them from contributing. I personally have more
fun contributing to QGIS than QGIS-Doc these last weeks(/months?).

For the writing side, I naively thought in the past that the main barrier
for contributors was the lack of precise instructions/how-tos (it could
have been for me) but despite our efforts to build guidelines more
descriptive and complete (with step-by-steps), few new contributors joined
us and they were very brief.
So If we have funds to finance people writing docs, let's do it. But
besides any contract with Yves, I think it could be nice to use it also as
an opportunity to attract new people to the doc writing. A long-term writer
is highly needed. And despite what I earlier mentioned about me working on
2.18, I think that any financed work should target QGIS3 (a backport can be
made if the fix applies to 2.18).

Btw, how do other FOSS write their documentation?

**Which documentation for QGIS 3?**

I am very delighted to see that Richard's QEP on linking application and
documentation is being implemented. Nice. However, this is at the
infrastructure level if I'm not wrong. What do we want to put as contents?
QGIS-Documentation currently provides 5 separate documents, maybe 6
(pending PRs :-) ) [3]. Status of some of these documents question me:

The Training Manual: this one is an useful document for beginners but was
written for QGIS 2.0 (?). It has got some fixes since, but also has a bunch
of issue reports that are not easy to tackle imho if you are not the author
nor had followed the exercices (which is my case but i might not be alone
among writers). I can't tell how closer it's currently with recent releases
but I wonder what it'll be with QGIS 3 (e.g., some plugins/tools described
in the manual like SPIT or Raster Terrain Analysis have been removed in
recent months... and could require some exercices to be reorganized)

The PYQGIS Cookbook: During the grant program, there were two proposals
about updating the Cookbook. Anita tried unsuccessfully to revive the
discussion about it later  [4]. I think that this is a major document to
update (and budgetize) because the API doc (which is worth updating, of
course) is not enough for the average developers (*a priori*, the majority
of plugin creators as I read) to build their tools. Having samples of code
is more than useful.

The PDF docs: We provide PDF docs to help people less connected to still
have a doc but these docs (at least the User manual) have some issues [5]
that don't make them always usable/readable.

Search: Have you ever made a research in the search bar of the doc? Then
did you find the results comprehensive/pertinent/right?
I also often see, in french forums, people adding to their comments links
to old QGIS docs (2.0, 2.2, 2.6) while there are more recent ones (QGIS
2.14 is the last released doc). I assumed that it's the "millesime" that is
returned by their web browser so I wonder why not recent docs are returned
in the searches and could that be improved?

I recently realized that QGIS has tools for spelling checks. Any chance to
have such tools in Docs repo where there's most likely more chance to have
spelling typos? Is that possible?

These last points are to say that, beyond writers, we also need developers
to help us maintain/improve the architecture/infrastucture of the doc repo
and make it more friendly for users and writers. Thanks, Richard.

As I mentioned at the beginning, I quickly write this message and may have
forgotten some points. And sorry for my french-to-english style writing.
I don't know on which points PSC could be of help but I had to express
them.

Hoping that it will be useful for the discussions and actions,
Harrissou

[0] https://github.com/qgis/QGIS-Documentation/pulse/monthly
[1] https://github.com/qgis/QGIS-Documentation/milestones
[2] https://github.com/qgis/QGIS/pull/3919
[3] https://github.com/qgis/QGIS-Documentation/issues/1566
[4] http://osgeo-org.1560.x6.nabble.com/Documentation-
proposals-Was-Discussion-on-the-QGIS-grant-proposals-td5289918.html
[5] https://github.com/qgis/QGIS-Documentation/issues?q=is%
3Aopen+is%3Aissue+label%3A%22PDF+Docs%22

2017-01-05 9:21 GMT+01:00 Paolo Cavallini <cavallini at faunalia.it>:

> Il 05/01/2017 09:18, Alexander Bruy ha scritto:
> > Hi,
> >
> > there is an ongoing work [0] on implementing generic help system for QGIS
> > based on Richard's QEP [1]. Maybe we should also adopt documentation
> > to this?
>
> +1
> reducing duplication and having the documentation more ready at hand are
> important targets.
> Thanks Alex.
>
> --
> Paolo Cavallini - www.faunalia.eu
> QGIS & PostGIS courses: http://www.faunalia.eu/training.html
> https://www.google.com/trends/explore?date=all&geo=IT&q=qgis,arcgis
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-psc
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20170109/5b1ebd85/attachment.html>