[QGIS-Developer] Documentation and algorithm news

Wed Mar 14 15:54:07 PDT 2018

Hi, 
Thanks Matteo and Richard for having brainstormed on this issue and for your outcome. And sorry to not have joined you.

Bear with me but i am less enthusiastic with some of the proposals for the reasons below

> On 03/14/2018 10:29 AM, matteo wrote:
> > Hi all,
> >
> > in the last weeks I've pointed out some problems we can have we the
> > documentation, so, together with Richard, these are the conclusions:
> >
> > * documentation repo will be branched together with QGIS release

Does it mean that current testing becomes 3.0 and testing targets 3.2?
When will the doc branched? As soon as the application is released?
Because of the low level of man power in doc writing, we decided to have a LTR based release plan. Plan we struggle to follow. With the proposed system, we could end up with 3/4 branches (from 2.18/3.0 to 3.4) and i'm afraid that the only changes among them reside in some algs description. Because there are other areas in user manual (but also other docs in a branch - cookbook, training, guidelines), there will be an overhead on back/forward porting commits. Is syncing some alg description with the manual release name worth all this trouble (see below for more context explanation)?

Another point related to quick releases is the "overload" of the doc landing page https://docs.qgis.org already crowded with some repetitive docs (dev or writers guidelines, GIS introduction in html and pdf + translations). For these docs, we can just keep a single version otherwise sooner we will kill our servers. See http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Management-of-release-independent-documents-td5318107.html for a discussion i fail to raise on this issue year ago.

> > * having these branches allows doc writers to update QGIS but,
> > especially, Processing Help files

Sorry. Even though i understand what you try to say, let me stress that there's currently room to update QGIS. There's already a lot to update in docs (336 issues in 3.0, 26 for 3.2). Master branch is desperately awaiting for writers to update QGIS. People should be aware of that.

As i said above, i'm really afraid that it will become only a Processing help files branch.
Let's analyze the current organisation:
* Users (should) know that the latest released doc is 2.18 and the testing doc targets 3.4, hence could contain features in development. 
* In the implemented help system, when you hit a help button in 3.0, 3.1 (up to 3.4) it will lead you to a page in the testing manual
  * if the alg does not change since 3.0, all is good
  * if it's a 3.1 documented alg, it's also good: user will find it from the application. And if a 3.0 user wonders why this documented alg is not available to him, refer to meaning of testing doc.
  * if a 3.0 alg is updated (new parameters or changed behavior), here could be the issue. Instead of branching the whole doc, maybe we could find a system of tag or something like that to help readers identify the appropriate description? I guess this kind of system might exist (also it should allow to easily find concerned algs so that we regularise the description once the LTR is released and "a new master branched").

> > * if you devs change something that is linked to Processing algorithm
> > (new algorithm OR changes to some parameter of existing algorithm) could
> > you please add the tag "ALGCHANGE" (other name suggestions are welcome)
> > in the commit message? This will open an issue in the doc repo with a
> > correct label (and hopefully assign this to me)
> >

Not sure it's either needed.
Many months i'm cleaning the doc repo, and if there are issues i can say are well tagged, it's the processing ones. 99% (to not say, ALL) of the issues related to Processing have [Processing] tag in the commit title. Devs already do that very well in QGIS repo so that i stopped applying the "Processing" label to the generated issue report. It was a needless repetitive task.
This to say that Processing issues are already easy to find in GitHub repo.

Now, do we need that someone points that the alg has changed (using an adhoc new tag) to figure it out? If the alg is already documented and there's a new issue report, then something has changed.

That said, it's not contradictory with a well described alg commit as suggested by Matthias. Thing we still miss because documenting alg help requires to check either the dialog or the code. 

Only the automatic assignment would not be handled by the current system unless we assign any processing-mentioned issue to you. 
> >
> > With this system we will have (at least) the chance to have Processing
> > Help updated and not loosing all the work done till now.
> >

Something that annoys me (and to be honest frustrates me a lot) in the recent discussions i read is my feeling that docs status/quality/interest is all about Processing help update. Don't get me wrong: i'm glad we covered those descriptions and we deliver algs with full help. And we have to keep updating the description (to avoid situations of the Cookbook or Training manual)
But processing help is not all; the Processing system itself is outdated: what are the recent changes? What are the options of Processing? How do models work? How to understand alg help? How to use/write algs/models?... There are things to update to help users understand Processing and i see no mention of this nowhere. 
And the rest of the docs, i'll avoid mentioning it here again (already made many calls) ... 

> > Feedbacks are more than welcome

Sorry to not come with a +1 and not be that positive in my feedback (i hope it's at least constructive) but while i share (and like) your interest in Processing help, i think that solutions we come with should keep in mind the big picture of documentation and ease the workload. And i'm afraid it's not fully the case here. 

Thanks for raising the question and i really wish we find a way to ensure long-term and sustainable update of (at least) Processing help. 

Cheers, 
Harrissou 
> >
> > Cheers and thanks to Richard for all the inputs!
> >
> > Matteo
> > _______________________________________________
> > QGIS-Developer mailing list
> > QGIS-Developer at lists.osgeo.org
> > List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> > Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> >
>
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer