[QGIS-Developer] Documentation and algorithm news

Thu Mar 15 03:34:40 PDT 2018

Hello all,

I have to agree with Harrissou. Going back to branch documentation at each
point release will not help, it will only create a bigger burden to a very
small team of interested people, with lots of commits needing to be ported
back or forward.

Although I have proposed to branch 3.0 documents from 2.18 before the
release in the past, I think that was a different situation, where 2.18
Docs were almost ready, and QGIS 3 release was yet undetermined.

I fail to see why Processing should be an exception regarding the rest of
the documentation. Everywhere, in the document there will be parts that
will be updated to 3.2 before the official release in QGIS 3.4 (hopefully).

Nevertheless, I am happy that someone is fully dedicated to it and I don't
want to frustrate Matteo in his demand to keep everything updated.

My suggestion is:

- Keep the branching as it is. That is, branch and release only for QGIS
3.4 LTR
- Keep updating the master branch for all 3.x features (if possible giving
priority to 3.0 features)
- Backport anything missing on 2.18, if applicable.
- For changes (in processing or not) specific to 3.2 or 3.4 add a note
saying "New in QGIS 3.2" (we could use a substitution for easy tracking).
That way, a QGIS 3.0 user using Testing Documentation understands that the
feature/parameter or whatever is not yet available for him. (This is how
Sphinx documentation does)
- Before the release of QGIS 3.4 Documentation, we clean up all those
messages.

IMHO, this methodology will keep the simplicity of the process, while
allows to document recent changes while they are still fresh.

About the ALGCHANGE, it's a +0 for me. I would prefer to keep it as simple
as possible and try not to have too many tags, The processing one would
with the risk that Developers.

Best regards,

Alex Neto

matteo <matteo.ghetta at gmail.com> escreveu no dia quinta, 15/03/2018 às
07:34:

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

-- 
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20180315/944dd9b2/attachment-0001.html>