Documentation

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

Documentation

pcav
Hi all,
we had a lengthy and I think fruitful discussion about the future of
documentation. I think time is ripe to take steps towards a concrete
solution.
AFAICT, a reasonable proposal stemming out of the discussion was:
* having a core documentation, listing all functions available with at
least a minimal description (this could be taken from the commit
description for the upcoming features, and the version number where it
first appeared can be added)
* allow comments by all interested parties on each function, to
encourage the addition of heterogeneous material, e.g. links to videos,
presentations, and more
UNclear how to handle translations:
* stick to English, and let people adding translations as comments as above
* starting with a multilingual structure from the beginning.
I think we agree that we want to keep a revision-controlled system, so
the main issue would be to have a web interface displaying each function
as a page, and allowing comments.
Of course there are other views, and nothing has been decided yet, so
alternative proposals are most welcome.
All best wishes.
--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

DelazJ
Hi Paolo, all

Le mer. 13 nov. 2019 à 19:26, Paolo Cavallini <[hidden email]> a écrit :
Hi all,
we had a lengthy and I think fruitful discussion about the future of
documentation. I think time is ripe to take steps towards a concrete
solution.
AFAICT, a reasonable proposal stemming out of the discussion was:

Do you refer to a recent PSC meeting (I can't find last meetings notes in the wiki btw) or to these last months discussions in the different mailing-lists ?
Anyways, I agree. Time to act.
 
* having a core documentation, listing all functions available with at
least a minimal description
 
 Is that something different from our current manuals? I mean, are there things in the current docs that would not have their place in the future docs, following this scenario? And what kind of contents would/could be added (other than the media you mention later)?

(this could be taken from the commit
description for the upcoming features, and the version number where it
first appeared can be added)
 
https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty represents the issue reports with NO description (because there was none in the commit). Add to that the issue reports whose description is only the commit title. Morality: writers still have to browse qgis/QGIS repository (or wait for the changelog to have more resources to pick from). So imho there's a work to do on the devs side to get them used to descriptive and easily understandable commits or PR.

* allow comments by all interested parties on each function, to
encourage the addition of heterogeneous material, e.g. links to videos,
presentations, and more
 
Do we have an example of what that could look like and how this is managed? Or is this something we'd "invent"? I must confess that I fail to see the "end product".

UNclear how to handle translations:
* stick to English, and let people adding translations as comments as above
* starting with a multilingual structure from the beginning.
I think we agree that we want to keep a revision-controlled system, so
the main issue would be to have a web interface displaying each function
as a page, and allowing comments.

Being a non-native English speaker and surrounded by people who do not speak English and love QGIS, I'd definitely prefer QGIS provides a way to get translation. Having materials in your language also contributes to QGIS adoption.
There is(was?) a Transifex web feature that allows, from what I understood at that time, to translate directly in the published docs. Never looked at it but maybe someone...
 
Of course there are other views, and nothing has been decided yet, so
alternative proposals are most welcome.
 
Maybe it's because I do not yet see what the proposals above would output, but I miss an information: what issue(s) are these changes trying to fix: the lack of contributors to docs, too many resources on personal blogs, docs not targetting the users need (ex of how-to suggestion), outdated information in docs, docs not being enough descriptive/detailed, docs being hard to contribute to, docs being hard to maintain/build, docs not being sexy, attracting more educational world contributors, prioritizing docs, no advertising on official docs... ? Cameron's thread as well as the user survey pointed many (different) levels of issues and since in my case I don't know which ones the PSC wants to prioritize, I'm pretty lost.
I think that without knowing what we want to fix/improve here, it's hard to come with comparable alternatives, if any. My 2cts.

Best wishes,
Harrissou

All best wishes.
--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

pcav
Thanks Harissou for your comments

Il 15/11/19 16:53, DelazJ ha scritto:

> Le mer. 13 nov. 2019 à 19:26, Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> a écrit :
>
>     Hi all,
>     we had a lengthy and I think fruitful discussion about the future of
>     documentation. I think time is ripe to take steps towards a concrete
>     solution.
>
>     AFAICT, a reasonable proposal stemming out of the discussion was:
>
>
> Do you refer to a recent PSC meeting (I can't find last meetings notes
> in the wiki btw) or to these last months discussions in the different
> mailing-lists ?

the discussions in the mailing lists

> Anyways, I agree. Time to act.

great

>     * having a core documentation, listing all functions available with at
>     least a minimal description
>
>  
>  Is that something different from our current manuals? I mean, are there
> things in the current docs that would not have their place in the future
> docs, following this scenario? And what kind of contents would/could be
> added (other than the media you mention later)?

it's different in the sense that we might stop trying to give
comprehensive description for every function, but rather to make sure
there is at least a short description for each, aiming therefore to
completedness rather than for comprehensiveness.
I'm not suggesting to throw away what we have, of course (even though it
might make sense to move it to the notes)

>     (this could be taken from the commit
>     description for the upcoming features, and the version number where it
>     first appeared can be added)
>
>  
> https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty
> represents the issue reports with NO description (because there was none
> in the commit). Add to that the issue reports whose description is only
> the commit title. Morality: writers still have to browse qgis/QGIS
> repository (or wait for the changelog to have more resources to pick
> from). So imho there's a work to do on the devs side to get them used to
> descriptive and easily understandable commits or PR.

agreed: we can require a minimal description for a PR to be accepted

>     * allow comments by all interested parties on each function, to
>     encourage the addition of heterogeneous material, e.g. links to videos,
>     presentations, and more
>
>  
> Do we have an example of what that could look like and how this is
> managed? Or is this something we'd "invent"? I must confess that I fail
> to see the "end product".

the idea was proposed by Tim, inspired by the PostgreSQL manual with
user comments
of course our situation is rather different, being an end user, desktop
software, but I think you got the idea

>     UNclear how to handle translations:
>     * stick to English, and let people adding translations as comments
>     as above
>     * starting with a multilingual structure from the beginning.
>     I think we agree that we want to keep a revision-controlled system, so
>     the main issue would be to have a web interface displaying each function
>     as a page, and allowing comments.
>
>
> Being a non-native English speaker and surrounded by people who do not
> speak English and love QGIS, I'd definitely prefer QGIS provides a way
> to get translation. Having materials in your language also contributes
> to QGIS adoption.

agreed

> There is(was?) a Transifex web feature that allows, from what I
> understood at that time, to translate directly in the published docs.
> Never looked at it but maybe someone...

if we use the current approach, the string will be translatable as usual

>     Of course there are other views, and nothing has been decided yet, so
>     alternative proposals are most welcome.
>
>  
> Maybe it's because I do not yet see what the proposals above would
> output, but I miss an information: what issue(s) are these changes
> trying to fix: the lack of contributors to docs, too many resources on
> personal blogs, docs not targetting the users need (ex of how-to
> suggestion), outdated information in docs, docs not being enough
> descriptive/detailed, docs being hard to contribute to, docs being hard
> to maintain/build, docs not being sexy, attracting more educational
> world contributors, prioritizing docs, no advertising on official
> docs... ? Cameron's thread as well as the user survey pointed many
> (different) levels of issues and since in my case I don't know which
> ones the PSC wants to prioritize, I'm pretty lost.
> I think that without knowing what we want to fix/improve here, it's hard
> to come with comparable alternatives, if any. My 2cts.

The aim is twofold:
* to have a timely, feature complete documentation, that we are able to
maintain with out current resources
* act as central repository of the myriads of documents in disparate
formats scattered everywhere; the system may encourage documentation
writer to add their content there to enjoy increased visibility, without
the associated high costs of bringing everything to a common format.
I must stress that nothing has been decided yet: this is a proposal,
better ones are welcome. What  believe it's important is to move forward.
Cheers.
--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matthias Kuhn 🌍
In reply to this post by DelazJ

Hi

On 11/15/19 4:53 PM, DelazJ wrote:

(this could be taken from the commit
description for the upcoming features, and the version number where it
first appeared can be added)
 
https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty represents the issue reports with NO description (because there was none in the commit). Add to that the issue reports whose description is only the commit title. Morality: writers still have to browse qgis/QGIS repository (or wait for the changelog to have more resources to pick from). So imho there's a work to do on the devs side to get them used to descriptive and easily understandable commits or PR.

This is mostly a limitation of the current system which is linking mostly commits, not pull requests. This will be much improved by opengis.ch's grant proposal to automatically open doc issues from pull requests. Denis should have time to work on that in the coming weeks.

Hope this clears the dust a bit at least in this area :)

Matthias


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

pcav
Hi Matthias,

Il 19/11/19 08:32, Matthias Kuhn ha scritto:

> Hi
>
> On 11/15/19 4:53 PM, DelazJ wrote:
>>
>>     (this could be taken from the commit
>>     description for the upcoming features, and the version number where it
>>     first appeared can be added)
>>
>>  
>> https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty
>> represents the issue reports with NO description (because there was
>> none in the commit). Add to that the issue reports whose description
>> is only the commit title. Morality: writers still have to browse
>> qgis/QGIS repository (or wait for the changelog to have more resources
>> to pick from). So imho there's a work to do on the devs side to get
>> them used to descriptive and easily understandable commits or PR.
>
> This is mostly a limitation of the current system which is linking
> mostly commits, not pull requests. This will be much improved by
> opengis.ch's grant proposal to automatically open doc issues from pull
> requests. Denis should have time to work on that in the coming weeks.
>
> Hope this clears the dust a bit at least in this area :)

thanks, this wil be a good improvement in the direction we are heading to.
Any opinion on the bigger picture?
Cheers.

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

ghtmtt
In reply to this post by DelazJ
Hi all,

> Do you refer to a recent PSC meeting (I can't find last meetings notes
> in the wiki btw) or to these last months discussions in the different
> mailing-lists ?
> Anyways, I agree. Time to act.

+1

>  
>
>     * having a core documentation, listing all functions available with at
>     least a minimal description
>
>  
>  Is that something different from our current manuals? I mean, are there
> things in the current docs that would not have their place in the future
> docs, following this scenario? And what kind of contents would/could be
> added (other than the media you mention later)?
>
>     (this could be taken from the commit
>     description for the upcoming features, and the version number where it
>     first appeared can be added)
>
>  
> https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty
> represents the issue reports with NO description (because there was none
> in the commit). Add to that the issue reports whose description is only
> the commit title. Morality: writers still have to browse qgis/QGIS
> repository (or wait for the changelog to have more resources to pick
> from). So imho there's a work to do on the devs side to get them used to
> descriptive and easily understandable commits or PR.
>
>     * allow comments by all interested parties on each function, to
>     encourage the addition of heterogeneous material, e.g. links to videos,
>     presentations, and more

I think we should admit that despite the ultra huge efforts of the
writers we have not the power to have docs updated with code, for a lot
of different reasons:

* dev # >>> writers
* sorry devs, but **sometimes** the PR descriptions is cryptic
* doc framework not easy for new contributors (this complexity leads
often to have only spot contributions)

therefore we should (maybe) change the doc vision. The suggestion of
Paolo and Tim to have only a skeleton of docs that points to the
description (as we have right now in the UI and that I really like and
think is super useful) + user comments/links(videos/whatever (in a i18n
framework) is maybe a solution.

Besides that, I also think that something has to be made on dev side:

* opengis.ch grant proposal should automate some process
* given that we push more to have PR than direct commits, a PR without
**at least** a doc skeleton that a writer can copy/paste cannot be merged

Other processes can be automated, but maybe this is the way to go

Cheers

Matteo









_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Alessandro Pasotti-2


On Tue, Nov 19, 2019 at 10:02 AM matteo <[hidden email]> wrote:
Hi all,

> Do you refer to a recent PSC meeting (I can't find last meetings notes
> in the wiki btw) or to these last months discussions in the different
> mailing-lists ?
> Anyways, I agree. Time to act.

+1
>  
>
>     * having a core documentation, listing all functions available with at
>     least a minimal description
>
>  
>  Is that something different from our current manuals? I mean, are there
> things in the current docs that would not have their place in the future
> docs, following this scenario? And what kind of contents would/could be
> added (other than the media you mention later)?
>
>     (this could be taken from the commit
>     description for the upcoming features, and the version number where it
>     first appeared can be added)
>
>  
> https://github.com/qgis/QGIS-Documentation/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+naughty
> represents the issue reports with NO description (because there was none
> in the commit). Add to that the issue reports whose description is only
> the commit title. Morality: writers still have to browse qgis/QGIS
> repository (or wait for the changelog to have more resources to pick
> from). So imho there's a work to do on the devs side to get them used to
> descriptive and easily understandable commits or PR.
>
>     * allow comments by all interested parties on each function, to
>     encourage the addition of heterogeneous material, e.g. links to videos,
>     presentations, and more

I think we should admit that despite the ultra huge efforts of the
writers we have not the power to have docs updated with code, for a lot
of different reasons:

* dev # >>> writers
* sorry devs, but **sometimes** the PR descriptions is cryptic
* doc framework not easy for new contributors (this complexity leads
often to have only spot contributions)

therefore we should (maybe) change the doc vision. The suggestion of
Paolo and Tim to have only a skeleton of docs that points to the
description (as we have right now in the UI and that I really like and
think is super useful) + user comments/links(videos/whatever (in a i18n
framework) is maybe a solution.

Besides that, I also think that something has to be made on dev side:

* opengis.ch grant proposal should automate some process
* given that we push more to have PR than direct commits, a PR without
**at least** a doc skeleton that a writer can copy/paste cannot be merged


Agreed, but with the following obvious exception: when a developer is willing to write the documentation him(her)self.

Please don't add another automatic PR blocker here that would slow down our normal workflow, Travis and peer-reviews are more than enough.

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

pcav
Hi all,

Il 19/11/19 10:16, Alessandro Pasotti ha scritto:
> Agreed, but with the following obvious exception: when a developer is
> willing to write the documentation him(her)self.

it makes sense to me

> Please don't add another automatic PR blocker here that would slow down
> our normal workflow, Travis and peer-reviews are more than enough.

got it, thanks.
cheers.

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc