[Qgis-community-team] Removing third party providers algorithms from QGIS Docs

[DelazJ]

Hi,

Thanks for your replies. Just some precision I'd like to add:

2018-07-03 9:15 GMT+02:00 matteo <matteo.ghetta at gmail.com>:

> Hi guys,
>
> > I know that those processing alg help pages are programmatically(?)
> > generated by Alexander B (in bcc), because we did not have anything
> > there, and it that way we at least had the list of parameters. The idea
> > was that humans then could add more information. We had some discussion
> > at that time to either put it all in separate files, or group them or
> > one file (we started with separate files, exploding the number of
> > resources for transifex).
> >
>

I did not check the history of those files but i'm pretty sure they didn't
get updates for years (other than visual cleanup or file restructuring).
And i'm sceptic that they get any in upcoming years (afaics there's no sign
out there that would contradict me).

> In general: having our own docs gives us a chance to have some
> > consistency, add our own text and images, they are translatable and
> > potentially to be packaged in an offline help package (still on the todo
> > list :-) ).
> >
>
Yes. If only we really have valuable text to show to users and our hundreds
of <put parameter description here> does not sound a plus-value imho.
Also, shouldn't we keep work on a project documentation close to the
project itself? I understood that we were getting rid of those providers
from Core and we would link to the upstream release. In that case, I
suppose that we'll be using the upstream release hence no more custom
parameters. so we can safely rely on upstream doc if it exists.
Shouldn't we follow the same logic as devs?

Maintaining a documentation of eg SAGA algs in QGIS docs while SAGA has a
documentation site sounds to me like spreading energy. Better maintain and
translate (if available or maybe help them to build that translation
platform) on their side. I don't know how things were at the time the
community made the choice to pull our own docs. Given the lack of love
those docs get, how hard it'll be to keep them up to date, the poor look of
those pages, and that there's a doc in SAGA side, should we continue to
keep them?

> But we should(!) link to them from within QGIS, else I agree we should
> > get rid of the burden to maintain them.
>
> I agree with Harrissou: there is already a huge effort to maintain just
> our algorithm docs (only speaking for Processing docs and not all the
> manual). Maintaining also gdal/saga/ecc.. is too much for different
> reasons:
>
> * some parameter changes and we have to update the docs by testing
> what's new
> * lack of docs from source (e.g. SAGA). If the source docs are poor
> there is no way (and also reasons I'll say) for us to document them
>
> Actually, I do not find that there is a lack or poor doc outside (compared
to what we propose). Some random choices:
Saga: see
https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/saga/terrain_analysis_hydrology.html#flow-width-and-specific-catchment-area
vs http://www.saga-gis.org/saga_tool_doc/2.2.0/ta_hydrology_19.html (see
whole index at http://www.saga-gis.org/saga_tool_doc/2.2.0/a2z.html)
R: i don't know how to find correspondences nor if that's the official site
but give a look to
https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/r/home_range_analysis.html#single-linkage-cluster-analysis
vs algs description at
https://stat.ethz.ch/R-manual/R-devel/library/stats/html/
Otb: See
https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/otb/feature_extraction.html#grayscalemorphologicaloperation-closing
vs
https://www.orfeo-toolbox.org/CookBook/Applications/app_GrayScaleMorphologicalOperation.html

Most of the times, our doc lists only the possible values and the default
one.

> It is a community choice, I think, if in QGIS we should be linking to
> > third-party docs or linking to QGIS docs (which then can link to the
> > third-party docs).
> >
> > We (as QGIS) really have a problem maintaining the docs.
> > People outside the community often complain about sparce documentation,
> > but (even with funding) we have problems keeping them up to date with
> > the developers. We really need more help, both from developers (which
> > more often should write some lines in the commit messages) and from
> > users (which could try to write some text).
> > Not sure if extra funding would help...
>
> Besides a lack of funding I see a lack of people.. I don't know how else
> we can attract more people to help documenting QGIS..
>
> Imho, it's really a lack of people. Not a money problem afaik. If I'm not
wrong (and Andreas could correct me), the budget assigned to documentation
in these last years was never covered.
And people that complain about sparce documentation should stop doing it
and try to give a hand (an hour per week or per month on an area they know
about is enough and would help others to fill the gaps in the parts they do
not know about). And removing those processing algs from our docs may give
a less sparce look to our docs.

Regards,
Harrissou

Cheers
>
> Matteo
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20180703/34240506/attachment-0001.html>