[Qgis-community-team] Manuals and help

Thu Jul 11 01:49:11 PDT 2013

Hi,

I agree with Victors suggestion and his experience with the SAGA community.
I think their community is just too small to handle this, so we should start
our own project and tell them, that they are welcome to contribute. And it is
great to see, that we already have some people to work on it - thanks a lot
for your offers!

I remember we also talked a while ago how to integrate SEXTANTE docs into
the qgis manual apart from the help tab within the modules. Here I would
also support the idea of having something extra, not directly part of the
manual. 

My idea for the SAGA module docs is:

* it should be part of the documentation repository under 
  https://github.com/qgis/QGIS-Documentation/tree/master/source/docs

* it should be written in RST with the same styles as the manual, so we
  can integrate it in the build/update/translation/... processes, like all
  other manuals
  https://github.com/qgis/QGIS-Documentation/tree/master/source/docs/documentation_guidelines  

* speaking for the manual I would still like to have kind of an
  introduction about SEXTANTE (we already have this) and then link to the
  extra SAGA manual. As we did/do it for the INSTALL.rst in the qgis
  sources, we could have this introduction as part the extra SAGA manual and
  just integrate it into the main qgis manual as a chapter. This should be
  no problem within the docs repo.

* as a note for help pages from other applications, such as GRASS or GDAL,
  we should just link to their web pages and integrate it in the SEXTANTE
  help tabs as it is already done, I think. It doesn't make sense to spend
  more effort on this at this point. 
  They are usually not translated but very well maintained, e.g for 
  * GRASS -> http://grass.osgeo.org/grass64/manuals/index.html
  * GDAL -> http://www.gdal.org/gdal_utilities.html

So, I would love to see that we keep this interaction between the qgis
manuals and the SEXTANTE module help in mind. So we are free to mix our
docs as needed and people find a consistent (infra)structure, if they want
to contribute.

Thanks 
Otto

Am Thu, 11 Jul 2013 09:51:39 +0200
schrieb Victor Olaya <volayaf at gmail.com>:

> Samuel
> 
> Thanks for you contribution. However, those docs are generated
> directly from the source code and do not have much information. Of
> course, they can be extended, but that means that the source code has
> to be modified in SAGA....which makes it impossible for people who do
> not know C++ to contirbute to the code, plus it would be the SAGA
> people who would handle contributions. Considering that they are not
> very active even in their own community and that they do not use
> github but a svn repo (that is, no pull request that are made
> easily...but patches...), I see that as a huge barrier.
> 
> I prefer to have something external, RST-based, easy for everyone to
> modify, and focused on how those algorithms should be used from
> SEXTANTE. Let's be a little selfish on that. If we eventually have
> good docs, I am sure the SAGA people will find the way of reusing our
> docs and incorporate them in their structure. Then we can start
> thinking about just taking them from upstream and coordinate with
> them. Until that happens, let's keep things on our side to make it
> easier.
> 
> Thanks everyone for you help- I plan to write some instructions about
> how to collaborate and maybe a list of algorithms that are more
> priority than others
> 
> I will keep you posted
> 
> Thanks
> Victor
> 
> 
> 
> 2013/7/11 Paolo Cavallini <cavallini at faunalia.it>:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> >
> > Il 11/07/2013 02:52, samuelmesa at gmail.com ha scritto:
> >> I managedthroughasmallPythonscriptto getsomethehtml
> >> helpofSAGAinthesextantsyntax:
> >>
> >> Script [1]: http://paste.ubuntu.com/5863377/
> >> Sextant html file [2]: http://goo.gl/Sr12A
> >>
> >> But there are some html files with errors due to special characters
> >> such as "/, (,)" in command names.
> >>
> >> To test this help should only copy the folder in the path:
> >>
> >> /usr/share/qgis/python/plugins/sextant/saga/
> >>
> >> I hope this can be a small solution for the moment.
> >
> > Great, thanks a lot. This opens back the issue:
> > * should we write our own docs, or
> > * contribute back upstream (adding only docs for the things changed in
> > sextante, as Victor outlined)?
> > In the second case, how could we write the docs and send them?
> > All the best.
> > - --
> > Paolo Cavallini - Faunalia
> > www.faunalia.eu
> > Full contact details at www.faunalia.eu/pc
> > Nuovi corsi QGIS e PostGIS: http://www.faunalia.it/calendario
> > -----BEGIN PGP SIGNATURE-----
> > Version: GnuPG v1.4.12 (GNU/Linux)
> > Comment: Using GnuPG with Icedove - http://www.enigmail.net/
> >
> > iEYEARECAAYFAlHeYacACgkQ/NedwLUzIr4k8wCfXHoqDfwB/0YEmO8fbQayAtpz
> > DtMAnjYCmxwx+2FPqyQTfGcqPw3Uxv0u
> > =fq89
> > -----END PGP SIGNATURE-----
> > _______________________________________________
> > Qgis-community-team mailing list
> > Qgis-community-team at lists.osgeo.org
> > http://lists.osgeo.org/mailman/listinfo/qgis-community-team
> _______________________________________________
> Qgis-community-team mailing list
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Geoinformatik Büro Dassau - http://www.gbd-consult.de
FOSSGIS consulting , training , support  and analysis
Ackerstrasse 144c  ,  D - 40233 Düsseldorf  , Germany
Tel: +49-(0)211-47468178 , Mobil: +49-(0)171-4687540

--
Community Advisor - QGIS Project Steering Committee