[Qgis-psc] Documentation work

[Yves Jacolin]

Hello PSC, Harrissou,

Thanks for raising this issue on documentation and send you opinion. 
Documentation is a long terme discussion, even if we improve things, all 
issues don't disappear :)

I try to answer/give my opinions on this but probably miss some question. Feel 
free to reply and ask again.

On Monday, January 09, 2017 13:37:28 DelazJ wrote:
> Hi,
> [..]
> 
> This issue actually has been floating around in my head for a moment,
Same for me :)

> 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, it still an heavy task and unfortunately I was very busy at the end of 
2016, move to a new home and still waiting for an internet access. So you are 
currently alone even if I tried to do some review last year. I basicly waiting 
for the next hackfest to improve my contributions and probably some week-end 
in february/march.

> 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.
There is something really important to think about documentation:
1. we are always behind QGIS code source
2. we can't manage branch currently in QGIS-Doc as branch aims to received bug 
fixes and we are not in the situation we can have branch/bug fixes in QGIS-Doc.

If one start to contribute to QGIS3, how to backport documentation of a new 
feature from QGIS 2.18 (from 2.148 to 3 or from 3 to 2.18, how to manage 
conflicts)?

> **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].
Yes, we should think about what can help us to find the correct information to 
document (where, what, how).

> 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?).
yes, but this means a bigger Documentation team and ask to contributors to 
review one PR for each PR sent (as an advice).

> 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.
This is the first part: you need to explain how to help from contributor, but 
this is not enough. You need to find them, interact with them. This is 
marketing stuff in some way. This is what I did last year with some "workclass" 
in the last hackfest, twetter message, etc. but this is not enough. When I am 
doing QGIS project for our customer I try to explain how they can help us/them 
to improve QGIS (-Doc). On Wednesday, I get in touch with someone who ask me 
how to contribute (I mean funding). I tell him that he can pay me to write 
documentation.

> 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).
Long term writer means someone who knows QGIS enough to write documentation, 
probably know small part of github and have enough time each months. Hard to 
find someone.

For me, we need crowdsourcing the documentation, that's meant get more people 
(well there another way as Paolo said ;) )

> 
> Btw, how do other FOSS write their documentation?
They have same problem as us but probably differently. We should be aware that 
the QGIS documentation is really good! Some FOSS project don't have any 
documentation (or any process), other ask to developer to write the 
documentation when they add new feature.

> **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)
Yes, definitively. But AFIAC, I focused on Doc, not training at this moment.

> The PYQGIS Cookbook: [..]

Nothing more to say here.
 
> The PDF docs: [..]

Not my priority (same as training) but that doesn't mean that it is important, 
of course.

> Search: [..]

Nothing more to add, you are right. This is something I though about, not more 
currently.

> 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?
Big +1! May I suggested to add a ticket?

> 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,
Sure it does! Thanks.

So to summarize, I would say: we need people and fund. About funding, I will 
be happy to work on the documentation if there is some funding. As 
documentation working group leader, I have a problem as I don't want to be 
seen to use this position to get some funding.

Anyway, this is difficult to find an easy and obvious solution (except the one 
from Paolo).

I am going to send a message to the QGIS linked group (9 176 members) to ask 
if they use the QGIS documentation or if any are available to help on the 
documentation. I will let you know the result.

Y.