[QGIS-Developer] Documentation and algorithm news

[matteo]

Hi Harrissou,

> 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)?

that is exactly the point: syncing only the Processing Help doc. As you
well know currently Processing docs are landed (for 3.0), but for the
current master some new algorithm is landed and some changes to existing
algorithms have been made.

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

This was also the initial idea, "detach" in some way the Processing Help
files from the whole folder, what comes in my mind, just thinking aloud:

* having a separate repo (BAD IDEA! for a tons of reasons)
* make separated branches (one for each release) where we now we will
only update Processing files and only build that documentation. This
should not overload the server. Redirecting all the other doc link of
that release to the testing branch. So we will have for example:

https://docs.qgis.org/3.2/en/docs/user_manual/processing_algs/qgis/cartography.htm
that will be build and really exists

https://docs.qgis.org/3.2/en/docs/user_manual/introduction/getting_started.html

that won't be build and that will be redirected to:

https://docs.qgis.org/testing/en/docs/user_manual/introduction/getting_started.html


I think this solution needs a lot of redirecting work

* .... other ideas?


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

ok, let's keep the existing [Processing] tag in the commit

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

you are perfectly right Harrissou and I can understand your frustration.
I also think that this Processing work has "resurrected" some interests
in the whole documentation (at least for me as you know ;) ).

Unfortunately we don't have man power to keep the doc updated with all
the code and I might be wrong, but I think this is also related with the
big 3.0 release. Main focus on the code and less to the doc.

I promise I'll do my best to help you out also for the general documentation


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

your critics are super appreciated! other feedbacks?

Cheers

Matteo