[Qgis-psc] Documentation work

[DelazJ]

Hi all,

Yves, comments inline

2017-01-13 12:22 GMT+01:00 Yves Jacolin <yjacolin at free.fr>:

> Hello PSC, Harrissou,
>
> [...]
>
> On Monday, January 09, 2017 13:37:28 DelazJ wrote:
> > Hi,
> > [..]
> >
> > 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.
>
> I hope you are well installed now.
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.
I was simply presenting the facts to others that do not follow the doc repo
life.


> > 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)?
>
> 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.
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 (https://github.com/qgis/QGIS-Documentation/issues?q=is%
3Aissue+is%3Aopen+label%3AEasy).


> > **People involvment**
> >
> > [...]
> > 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.
>
> Thanks to do the salesman :-)


> > 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.
>
> 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 :-).


> For me, we need crowdsourcing the documentation, that's meant get more
> people
> (well there another way as Paolo said ;) )
>
> >[...]
> >
> > 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?
>
> In redmine or Github Doc repo? Or both?


> > 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.
>
> 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.

Harrissou

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.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20170113/b8065c2f/attachment.html>