[Qgis-community-team] [Qgis-developer] Moving the install instructions to a more sexy, visible, coherent and translatable page in qgis.org

Sat Apr 23 14:00:47 PDT 2016

Hi,

Thanks for your comments. You both are pointing what I was afraid of and
mentionned at the end of my message: how to keep up to date the install
instructions?
And to be honest I'd prefer an up to date instruction in english only
(though not easy to use) to a translated but deprecated one. My intention
wasn't to move the INSTALL instruction itself from the QGIS repo. I agree
that we should keep an INSTALL doc near every QGIS release.
My concern is should we and how do we get back its contents into website
(or maybe, documentation?) repo. I don't know about magic tools that can be
used so can't be of any help. Sorry!

The INSTALL doc is imho one other and big advocate of QGIS being an
inclusive project, cross-platform, accessible to _any_ newcomer  and that
developers care about that.  For such reasons, I think it deserves more
exposure. The current generated preview is somehow hidden (though you can
find links to it in the website), isolated from QGIS doc and not that funny
to read. These last months a lot of work has been done on documenting how
people can get involved in the project, from writer, bug reporter,
translator to developer, newbie or not (which repo for which issue, how to
use git, qt, rst, code and doc writing rules...) . And I feel that "how to
compile QGIS" is a missing gap.

About potential users, I think a documented feature has more chance/is
easier to be used than not documented. For having tried unsuccessfully to
build QGIS on Windows 8 about a year ago, I wasn't able to decide if it was
because I didn't well understand the steps or if it was because I hadn't
the same version of applications used in the instructions. So, shame on me,
I gave up!
In a more exposed situation, we can expect feedback of community (and not
only Juergen and few people- thanks to you) about potential changes/updates
on third-party tools used, comments on the quality of the description
(e.g., while converting the text into rst, I found that there are some
broken links under 4.3.2.2, 4.3.2.3, 4.3.2.7 - just other dependencies
btw)...
I may be too much optimistic but I think if there's a somehow easy and
long-term clean way to have these instructions available near our other
official documents and accessible to our wider community, let's do it.
Otherwise, let's update the INSTALL doc to remove mention of availability
in our website/documentation, in any translated language (at that time I
spent time lookig for the translated version).

Sorry for a so long post

Regards,
Harrissou

2016-04-23 19:52 GMT+02:00 Tim Sutton <tim at kartoza.com>:

> Hi
>
>
> On 23 Apr 2016, at 16:53, Richard Duivenvoorde <rdmailings at duif.net>
> wrote:
>
>
> Hi,
>
> during last hackfest I actually also did this, point was that currently
> there is some 'magic' if I understand correct from Juergen, which would
> be broken if be bring those pages to rst…
>
>
>
>
>
> I agree with you that rst would be the preferred format, but feel that
> as Juergen is actually keeping those notes up to date, he has to ok with
> that.
>
> @jef: maybe you can elaborate a little more on this?
>
>
>
> I’m popping in here a bit because some of this is my legacy. The INSTALL
> is built using text2tags (a markup language before markdown became
> popular). We could probably migrate to using RST sometime but the
> attraction of t2tags is that it is very light weight (single simple small
> binary to compile the doc) and the INSTALL docs in the source code means it
> usually will match whatever version of QGIS you checkout from GIT. If we
> move the management out of the code tree and into the docs tree then we
> create a cross dependency on the two repos meaning that when we e.g. do a
> release we need to be sure to compile the INSTALL docs in the docs tree and
> copy the generated file over to the code source tree - and be sure we are
> compiling the right docs sources to match the the version of the code
> sources. That all sounds a little complicated to me compared to the current
> system…
>
> What about we maintain a small sphinx project inside the code tree and
> then do some git submodule magic to include that into the docs repo. Can
> you use submodules to include only a directory from another repo? I agree
> it would be nice to be able to have the INSTALL docs translated, though I
> don’t know if it is worth the effort (i.e. how many people will actually
> use them).
>
> Regards
>
> Tim
>
>
> Regards,
>
> Richard
>
> On 22-04-16 17:28, DelazJ wrote:
>
> Hi,
>
> Currently, when someone is looking for steps to compile a QGIS release,
> he'll will find them in the QGIS repo [0]
>
> I personally don't like that page and from a non-english speaker and
> non-developer looking for a howto, I didn't like it not being
> translated. And there are pages from the translated website that
> directly link to this page (leaving a fully translated page to a
> specialized page totally in english from within the QGIS project doesn't
> really sound good to me).
>
> Then, reading the introduction of this notice, you'll find assertions
> such as:
> - "You can download this document as part of the QGIS 'User and
> Installation Guide' in HTML and PDF format via http://qgis.org."
> - "Translations of this document can also be downloaded at the
> documentation area of the QGIS project at http://qgis.org."
> AFAICS, this text is available nowhere in the manuals and there's no
> translated version.
>
> SO, does it make sense to move it to somewhere like
> http://www.qgis.org/en/site/getinvolved/development/index.html?
> It'll complete all other chapters on development matters, will be more
> visible, sexy and translatable.
>
> The issues I can't figure out how they can be solved are:
> - what will be the status of the current page, in the QGIS repo?
> - how will update be managed?
>
> Comments are welcome. I'd have loved to show you this chapter in context
> but I'm unable to build the website [1] so you may need to review the PR
> #343 [2](I've RSTed the text)
>
> <https://github.com/qgis/QGIS-Website/pull/343>
> Thanks,
> Harrissou
>
> [0]
>
> http://htmlpreview.github.io/?https://github.com/qgis/QGIS/blob/master/doc/INSTALL.html
> [1]
>
> http://osgeo-org.1560.x6.nabble.com/Unable-to-build-QGIS-Website-with-Paver-td5262145.html
>
> [2] https://github.com/qgis/QGIS-Website/pull/343
>
>
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
>
> —
>
>
>
>
>
>
> Tim Sutton
>
> Co-founder: Kartoza
> Project chair: QGIS.org <http://qgis.org>
>
> Visit http://kartoza.com to find out about open source:
>
> Desktop GIS programming services
> Geospatial web development
> GIS Training
> Consulting Services
>
> Skype: timlinux
> IRC: timlinux on #qgis at freenode.net
>
>
> Kartoza is a merger between Linfiniti and Afrispatial
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160423/15f77a3d/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: KartozaNewLogoThumbnail.jpg
Type: image/jpeg
Size: 6122 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160423/15f77a3d/attachment.jpg>