<div dir="ltr"><div>Hi all,<br><br></div>Yves, comments inline<br><div><div class="gmail_extra"><br><div class="gmail_quote">2017-01-13 12:22 GMT+01:00 Yves Jacolin <span dir="ltr"><<a href="mailto:yjacolin@free.fr" target="_blank">yjacolin@free.fr</a>></span>:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello PSC, Harrissou,<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span><span class="gmail-st">[...]</span><br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span>
On Monday, January 09, 2017 13:37:28 DelazJ wrote:<br>
> Hi,<br>
> [..]<br>
<span class="gmail-m_-6568327227959792228gmail-">></span><span class="gmail-m_-6568327227959792228gmail-"><br>
> Browsing stats of the doc repo [1], we currently have:<br>
> * >120 issues for 3.0<br>
> * 72 for 2.16 and 2.18<br>
> * 40 without milestones, sometimes very old issues or global issues related<br>
> to the doc infrastructure/organisation itself.<br>
> A heavy task !<br>
</span>yes, it still an heavy task and unfortunately I was very busy at the end of<br>
2016, move to a new home and still waiting for an internet access. So you are<br>
currently alone even if I tried to do some review last year. I basicly waiting<br>
for the next hackfest to improve my contributions and probably some week-end<br>
in february/march.<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span></blockquote><div>I hope you are well installed now.<br>Honestly I was not complaining nor blaming you or any other writer (and as I said I also left the repo at some point). And the last time I really needed one to review my PR, I simply asked the team and few hours later you were doing it.<br>I was simply presenting the facts to others that do not follow the doc repo life. <br> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-m_-6568327227959792228gmail-">
> Yes, LTR releases should be the target of documentation. But we currently<br>
> do not know when the next LTR (3.2) will be available and until that<br>
> moment, I think that the majority of users will likely stick to a 2.x<br>
> version. Reason why I think a 2.18 doc should be released. I personally do<br>
> not consider 3.x issues yet when contributing to doc. It can be seen like<br>
> overloading the work given that some features in 2.x are broken/removed in<br>
> 3.0 but other features are improvements of existing features and require<br>
> them to be prealably filled. So given that I don't have any idea of the<br>
> balance, I'm still focusing on 2.18. Maybe it's now time to have, like it<br>
> was done for QGIS, two branches in Doc repo (master_2/2.18 and<br>
> master/testing), so that available people can begin tackling some features<br>
> of QGIS3.<br>
><br>
> So, in any case, If we want a 3.2 doc to be released nearby QGIS3.2<br>
> release, we obviously need more people involved in QGIS Documentation and<br>
> also an idea of what we would like a QGIS3 documentation to look like.<br>
</span>There is something really important to think about documentation:<br>
1. we are always behind QGIS code source<br>
2. we can't manage branch currently in QGIS-Doc as branch aims to received bug<br>
fixes and we are not in the situation we can have branch/bug fixes in QGIS-Doc.<br>
<br>
If one start to contribute to QGIS3, how to backport documentation of a new<br>
feature from QGIS 2.18 (from 2.148 to 3 or from 3 to 2.18, how to manage<br>
conflicts)?<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span></blockquote><div>Yes, we'll always be behind QGIS. Normal! But I think we also agree that the doc release should be as far as possible quite near the application release. Sorry I don't get your point 2.<br>I'm not sure that there'll be so many conflicts in backporting, it's not a matter of python3 vs python2 or pyqt5 vs pyqt4; it's all about plain texts using the same rst language, so cherry-picking commits won't be that hard. We do it when needed (e.g., between 2.18 and 2.14). And issues are milestoned so we know what to document where (whether it's for 3.0 only or also 2.18). The main advantage in branching a 3.0 is to begin to fix easy issues (<a href="https://github.com/qgis/QGIS-Documentation/issues?q=is%3Aissue+is%3Aopen+label%3AEasy" target="_blank">https://github.com/qgis/QGIS-<wbr>Documentation/issues?q=is%<wbr>3Aissue+is%3Aopen+label%3AEasy</a><wbr>).<br> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-m_-6568327227959792228gmail-">
> **People involvment**<br>
><br></span><span class="gmail-m_-6568327227959792228gmail-"></span><span class="gmail-st">> [...]</span><br>
<span class="gmail-m_-6568327227959792228gmail-"></span><span class="gmail-m_-6568327227959792228gmail-">> For the writing side, I naively thought in the past that the main barrier<br>
> for contributors was the lack of precise instructions/how-tos (it could<br>
> have been for me) but despite our efforts to build guidelines more<br>
> descriptive and complete (with step-by-steps), few new contributors joined<br>
> us and they were very brief.<br>
</span>This is the first part: you need to explain how to help from contributor, but<br>
this is not enough. You need to find them, interact with them. This is<br>
marketing stuff in some way. This is what I did last year with some "workclass"<br>
in the last hackfest, twetter message, etc. but this is not enough. When I am<br>
doing QGIS project for our customer I try to explain how they can help us/them<br>
to improve QGIS (-Doc). On Wednesday, I get in touch with someone who ask me<br>
how to contribute (I mean funding). I tell him that he can pay me to write<br>
documentation.<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span></blockquote><div>Thanks to do the salesman :-)<br> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-m_-6568327227959792228gmail-">
> So If we have funds to finance people writing docs, let's do it. But<br>
> besides any contract with Yves, I think it could be nice to use it also as<br>
> an opportunity to attract new people to the doc writing. A long-term writer<br>
> is highly needed. And despite what I earlier mentioned about me working on<br>
> 2.18, I think that any financed work should target QGIS3 (a backport can be<br>
> made if the fix applies to 2.18).<br>
</span>Long term writer means someone who knows QGIS enough to write documentation,<br>
probably know small part of github and have enough time each months. Hard to<br>
find someone.<br>
<br></blockquote><div>Yes, maybe... reason why a paid person could be an option. Maybe things will be easier with the new structure being implemented, once it's explained to us :-).<br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
For me, we need crowdsourcing the documentation, that's meant get more people<br>
(well there another way as Paolo said ;) )<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span><span class="gmail-st">>[...]</span><br>
<span class="gmail-m_-6568327227959792228gmail-">><br>
> I recently realized that QGIS has tools for spelling checks. Any chance to<br>
> have such tools in Docs repo where there's most likely more chance to have<br>
> spelling typos? Is that possible?<br>
</span>Big +1! May I suggested to add a ticket?<br>
<span class="gmail-m_-6568327227959792228gmail-"><br></span></blockquote><div>In redmine or Github Doc repo? Or both?<br> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-m_-6568327227959792228gmail-">
> Hoping that it will be useful for the discussions and actions,<br>
</span>Sure it does! Thanks.<br>
<br>
So to summarize, I would say: we need people and fund. About funding, I will<br>
be happy to work on the documentation if there is some funding. As<br>
documentation working group leader, I have a problem as I don't want to be<br>
seen to use this position to get some funding.<br>
<br></blockquote><div>I'd rather say: "we need people". According to Andreas, we already have some funds available. We miss someone willing to take the keyboard. And I personally do not have problem if it's you as far as the process is clear for everyone and transparent. I think anyone candidating to this can easily make his proposal.<br><br></div><div>Harrissou<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Anyway, this is difficult to find an easy and obvious solution (except the one<br>
from Paolo).<br>
<br>
I am going to send a message to the QGIS linked group (9 176 members) to ask<br>
if they use the QGIS documentation or if any are available to help on the<br>
documentation. I will let you know the result.<br>
<span class="gmail-m_-6568327227959792228gmail-HOEnZb"><font color="#888888"><br>
Y.<br>
<br>
</font></span></blockquote></div><br></div></div></div>