[Qgis-community-team] Is releasing QGIS Documentation still in the plan?

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

[Qgis-community-team] Is releasing QGIS Documentation still in the plan?

DelazJ
Hi all,

I was about to write yet another mail explaining why/what/when/where/who... (and other stuffs like these) about QGIS-Documentation given the low interest (almost none) put in the review of the tens of pull-requests [0] and questions opened these last weeks. But I think that the title of this message better reflects my current feelings, requires an answer and saves all of us from repetition [1].

PS: This message is not addressed to the PSC (I'm aware of their position [2] and efforts - so please PSC old and new members, don't reply) but to the Community (I wonder if i should have sent this to the qgis-user list but let's see what qgis-community thinks about that, first).

Regards,
Harrissou


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

ghtmtt
Hi Harrissou,

thanks for raising this. I would say we really need more people working
on the documentation. I don't know how to find other contributors but we
have.

Just run

git shortlog -sn --after="2018-01-01"

and you can see that there are a few contributors for this repo.

IMHO now that images preview are visible in github there is easier also
for other people to contribute.

I cannot understand if there are some people out there that want to
contribute but the system "complexity" (git + sphinx + ...) blocks them
to do that.

Just thinking aloud: do you think that a short video tutorial could be
useful? We have a nice documentation for who wants to step in, but a
short and explicit video maybe is more sexy?


Thanks again for raising this

Cheers

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

Yves Jacolin
Hello,

I am more pessimistic. My opinion is just that documentation is not fun
(at least not as feature development is), boring and not valuable from a
skills point of view (I don't mean valuable on the project side).

All in all, people could be tired to work on such a tasks in the long
term. This is what I feel from Harrissou email and from my own experience.

Unfortunately, I didn't have time the previous year and can't go to the
haskfest which doesn't help to contribute.

Sorry for a so pessimistic email.

Y.


Le 13/04/2018 à 11:39, matteo a écrit :

> Hi Harrissou,
>
> thanks for raising this. I would say we really need more people working
> on the documentation. I don't know how to find other contributors but we
> have.
>
> Just run
>
> git shortlog -sn --after="2018-01-01"
>
> and you can see that there are a few contributors for this repo.
>
> IMHO now that images preview are visible in github there is easier also
> for other people to contribute.
>
> I cannot understand if there are some people out there that want to
> contribute but the system "complexity" (git + sphinx + ...) blocks them
> to do that.
>
> Just thinking aloud: do you think that a short video tutorial could be
> useful? We have a nice documentation for who wants to step in, but a
> short and explicit video maybe is more sexy?
>
>
> Thanks again for raising this
>
> Cheers
>
> Matteo
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
http://yjacolin.gloobe.org



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

DelazJ
In reply to this post by ghtmtt
Hi Matteo,

The issue i'm raising today is not about writing docs (which may require more capabilities, or at least more investment) but about:
- reviewing what's proposed
- and answering some questions either to give more details about some features (Nyall and Matthias are really reactive for that - thanks guys!) or discuss some proposed orientation.

2018-04-13 11:39 GMT+02:00 matteo <[hidden email]>:
Hi Harrissou,

[...]

I cannot understand if there are some people out there that want to
contribute but the system "complexity" (git + sphinx + ...) blocks them
to do that.

Actually, you don't need git or sphinx (a little, though) or dev environment to write docs. Thinking that (and I often read that) is wrong; a fork of the repo and a web browser are enough. And you can do almost everything. And how that works is stated in the https://docs.qgis.org/testing/en/docs/documentation_guidelines/first_contribution.html#using-github-web-interface
Also do not forget that Tim made a call for plain text documentation, no rst nor formatting needed, just simple text (and we got.... ONE proposal).

Just thinking aloud: do you think that a short video tutorial could be
useful? We have a nice documentation for who wants to step in, but a
short and explicit video maybe is more sexy?

Alexandre gave a course during the last meeting: https://www.youtube.com/watch?v=5NifJYjBc2c (not sure that has changed anything, for the moment)

Reason why I'd like to know if we collectively think that we should discontinue this part of QGIS or no.

H.

Thanks again for raising this

Cheers

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

DelazJ
In reply to this post by Yves Jacolin
Hi Yves,

2018-04-13 11:47 GMT+02:00 Yves Jacolin <[hidden email]>:
Hello,

I am more pessimistic. My opinion is just that documentation is not fun
(at least not as feature development is), boring and not valuable from a
skills point of view (I don't mean valuable on the project side).

I would like to disagree. Documentation may not be fun for devs, but QGIS community is not all about devs and we should stop using this argument; there are teachers, trainers, blogposters, users... people who are used to communicate about QGIS features and this is an area that should be of interest to them or should be within their reach.

Also, maybe because I'm not a dev, working on docs made me learn some python, git and rst things that are not part of my daily work so yes, I developed some skills (and interest) I think.
Now related to my daily work, writing the docs teaches me a lot of features and subtleties in using QGIS. And I'm not sure I'd have found them if not doing that. Sidenote: bug reporting comes also with that.

All in all, people could be tired to work on such a tasks in the long
term. This is what I feel from Harrissou email and from my own experience.

Actually, I'm not tired (or maybe I'm not conscious of that) but at the beginning, for the fun, I was wondering how many pull requests would be opened before any review begins and now I think that it's not worth spending (wasting?) time in some(community)thing if no one seems interested in it. There are many other things to do out there.

H.

Unfortunately, I didn't have time the previous year and can't go to the
haskfest which doesn't help to contribute.

Sorry for a so pessimistic email.

Y.


Le 13/04/2018 à 11:39, matteo a écrit :
> Hi Harrissou,
>
> thanks for raising this. I would say we really need more people working
> on the documentation. I don't know how to find other contributors but we
> have.
>
> Just run
>
> git shortlog -sn --after="2018-01-01"
>
> and you can see that there are a few contributors for this repo.
>
> IMHO now that images preview are visible in github there is easier also
> for other people to contribute.
>
> I cannot understand if there are some people out there that want to
> contribute but the system "complexity" (git + sphinx + ...) blocks them
> to do that.
>
> Just thinking aloud: do you think that a short video tutorial could be
> useful? We have a nice documentation for who wants to step in, but a
> short and explicit video maybe is more sexy?
>
>
> Thanks again for raising this
>
> Cheers
>
> Matteo
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team

--
http://yjacolin.gloobe.org



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

Alexandre Neto
I think we need to put this conversation at least in the devs list, not everybody is in this community list, so we probably end up talking to ourselves (which may still happen, since Docs aren't sexy).

I don't think we will be able to do the documentation only with volunteers. We will need to professionalize it. We need to pay people to write documentation, and even to review it.

Unfortunately, even having money to spend, it seems difficult to get people that are free to do it...

It's very frustrating to write lots of documentation, and then get stuck by the lack of reviews. I know Harrissou is in that position. I would suggest that, if after a period of time, the PR has no reviews at all, its owner is free to merge it. I know it's not ideal but is better than having outdated documentation while someones updates are in standby forever.

BTW, it's on my TODO list to update the documentation video, focusing on the github approach. ut I don't know when I will have time for that.

Best regards,

Alexandre Neto


DelazJ <[hidden email]> escreveu no dia sexta, 13/04/2018 às 11:21:
Hi Yves,

2018-04-13 11:47 GMT+02:00 Yves Jacolin <[hidden email]>:
Hello,

I am more pessimistic. My opinion is just that documentation is not fun
(at least not as feature development is), boring and not valuable from a
skills point of view (I don't mean valuable on the project side).

I would like to disagree. Documentation may not be fun for devs, but QGIS community is not all about devs and we should stop using this argument; there are teachers, trainers, blogposters, users... people who are used to communicate about QGIS features and this is an area that should be of interest to them or should be within their reach.

Also, maybe because I'm not a dev, working on docs made me learn some python, git and rst things that are not part of my daily work so yes, I developed some skills (and interest) I think.
Now related to my daily work, writing the docs teaches me a lot of features and subtleties in using QGIS. And I'm not sure I'd have found them if not doing that. Sidenote: bug reporting comes also with that.

All in all, people could be tired to work on such a tasks in the long
term. This is what I feel from Harrissou email and from my own experience.

Actually, I'm not tired (or maybe I'm not conscious of that) but at the beginning, for the fun, I was wondering how many pull requests would be opened before any review begins and now I think that it's not worth spending (wasting?) time in some(community)thing if no one seems interested in it. There are many other things to do out there.

H.

Unfortunately, I didn't have time the previous year and can't go to the
haskfest which doesn't help to contribute.

Sorry for a so pessimistic email.

Y.


Le 13/04/2018 à 11:39, matteo a écrit :
> Hi Harrissou,
>
> thanks for raising this. I would say we really need more people working
> on the documentation. I don't know how to find other contributors but we
> have.
>
> Just run
>
> git shortlog -sn --after="2018-01-01"
>
> and you can see that there are a few contributors for this repo.
>
> IMHO now that images preview are visible in github there is easier also
> for other people to contribute.
>
> I cannot understand if there are some people out there that want to
> contribute but the system "complexity" (git + sphinx + ...) blocks them
> to do that.
>
> Just thinking aloud: do you think that a short video tutorial could be
> useful? We have a nice documentation for who wants to step in, but a
> short and explicit video maybe is more sexy?
>
>
> Thanks again for raising this
>
> Cheers
>
> Matteo
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team

--
http://yjacolin.gloobe.org



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

ghtmtt
Hi,

> I think we need to put this conversation at least in the devs list, not
> everybody is in this community list, so we probably end up talking to
> ourselves (which may still happen, since Docs aren't sexy).

+1 (even if we maybe will keep up the discussion by ourselves ;) )

> I don't think we will be able to do the documentation only with volunteers.
> We will need to professionalize it. We need to pay people to write
> documentation, and even to review it.
>
> Unfortunately, even having money to spend, it seems difficult to get people
> that are free to do it...
>
> It's very frustrating to write lots of documentation, and then get stuck by
> the lack of reviews. I know Harrissou is in that position. I would suggest
> that, if after a period of time, the PR has no reviews at all, its owner is
> free to merge it. I know it's not ideal but is better than having outdated
> documentation while someones updates are in standby forever.

I'm + 1 also on this. I think that the errors that a merged PR could
introduce are still better to have a long cue of unmerged PR. Knowing
that it is always better to have reviewed docs, but maybe (just maybe)
errors are easier to find during the final reading of the docs..

> BTW, it's on my TODO list to update the documentation video, focusing on
> the github approach. ut I don't know when I will have time for that.

just ping if you need help

Thanks

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] Is releasing QGIS Documentation still in the plan?

DelazJ
Hi,

2018-04-13 14:29 GMT+02:00 matteo <[hidden email]>:
Hi,

> I think we need to put this conversation at least in the devs list, not
> everybody is in this community list, so we probably end up talking to
> ourselves (which may still happen, since Docs aren't sexy).

+1 (even if we maybe will keep up the discussion by ourselves ;) )

Sadly true!
 
> I don't think we will be able to do the documentation only with volunteers.
> We will need to professionalize it. We need to pay people to write
> documentation, and even to review it.
>
> Unfortunately, even having money to spend, it seems difficult to get people
> that are free to do it...
>
ditto ;(
Though review is often less time consuming than writing...
 
> It's very frustrating to write lots of documentation, and then get stuck by
> the lack of reviews. I know Harrissou is in that position. I would suggest
> that, if after a period of time, the PR has no reviews at all, its owner is
> free to merge it. I know it's not ideal but is better than having outdated
> documentation while someones updates are in standby forever.

I'm + 1 also on this. I think that the errors that a merged PR could
introduce are still better to have a long cue of unmerged PR. Knowing
that it is always better to have reviewed docs, but maybe (just maybe)
errors are easier to find during the final reading of the docs..

Thanks to those who reviewed some of the existing pull-requests.
My concern with "no review - just merge" rule is that issue in docs are hard to find later. We have no tools to check for typos, for wrong formulation (sorry but English is not the mother tongue of most of us), wrong description of tool behavior (That's what personally worries me the most, I often try tools before documenting but unfortunately things are not always obvious and reviews help to reduce mistakes). And doing that alone is just boring! Also, the consequences are 1/mislead users and 2/overload translators work (a first time in translating the wrong text - in case it's clear enough to try a translation - and a second time when the issue is found and fixed in the English part).
Using that "no review - just merge" rule should be an exception and not a rule by default.

That said, I finally merged a dozen of unreviewed/"not discussed" PRs that had more than 2 weeks, as I feel they'd not get much attention, and closed around 20 issue reports. The nice news was that we've dropped to less than 400 issues to document... until few hours ago.
A nice goal would be to keep that number as a maximum threshold for the issue queue. There are already a lot of new (and shorter) PRs that would help to reach that goal so please, continue to review.
Unless doc release is stopped (which does not seem to be the *expressed* trend), I'll try to keep the goal achieved (and if possible, lower that limit) until... 3.4 doc release.
After that, without new docs initiative/contributor, it could be a nice opportunity to learn c++ ;)

There was that QGIS survey launched in 2015 [0] and if I'm not wrong, Anita published later an analysis of the teachings. I can't find it. Can someone point me to that results, please?
I'd be really interested in another round. While I'm more interested in how the documentation perception may have (or not) changed these last years (if/who/why  knows/uses/does not contribute/needs/misses?) and docs future, it can also be the opportunity to take the community's pulse more formally and see if the project has improved or not (regarding their remarks three years ago).
Maybe, this can be done between 3.2 and 3.4 releases (3.x would not be that new "brand" and no LTR yet)? We would then also have time to prepare and translate such survey...

[0] http://blog.qgis.org/2015/10/15/take-the-qgis-user-survey/ (not available but...)

Regards,
Harrissou

> BTW, it's on my TODO list to update the documentation video, focusing on
> the github approach. ut I don't know when I will have time for that.

just ping if you need help

Thanks

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team