[Qgis-community-team] Blockers to start contributing to QGIS documentation (was: User question of the month)

[Harrissou]

Hi Nick, all

Thanks for your reply. I was afraid my message fell in the abyss of the Internet ;)

Le 29 octobre 2019 13:32:14 GMT+01:00, Nick Bearman <nick at geospatialtrainingsolutions.co.uk> a écrit :
>Hi community,
>
>I've not read the original post closely, but my hunch is that compiling
>the
>documentation on a Windows machine is the blocker. I've never tried
>getting
>Sphinx running on a Windows machine but it looks horrible.

I tried years ago to follow the "make" instructions and neither succeeded to build docs on Windows. Too many upstream documentation to read for a non developer to understand what are these (msys/cygwin/setup_tools, virtual environment, pip... and how all these play, in a non obvious way for a windowser btw). The good news is that the docs readme provides different ways to build (including on Windows) and I ended up using the Paver [0] route which had proven successful.
Moreover, recently, Rosa updated the build instructions on Windows (and it works on Linux too) with simpler steps [1]. Maybe should you give it another try.
But...

> My approach
>is
>to just use Git locally, and send in PRs that way. This means I have no
>way
>of previewing it properly, but I end up keeping my fingers crossed!
>

... The GitHub preview is trustworthy. And don't cross too much your fingers (not good for them); if there's anything wrong in your contribution, Travis or a reviewer will catch or help you fix it. And in the documentation side we do not expect everyone to have built the docs locally, reason why the steps we are promoting for years are the GitHub online modifications [2].
So no worries if the PR is not perfect for the first shot.

>The material I used at the FOSS4G UK Workshop used this approach.
>Presentation at
>https://www.dropbox.com/transfer/cap_pid_ft%3AAAAAAAPJCGaAT6Guqh3DLrjhqtN_Kiu-6Tj2R-LhUUho-KB34PUGBr4
>and experimental Repo here
>https://github.com/nickbearman/Contributing-to-QGIS-Documentation. I
>need
>to write up a blog post and share this properly (it's on my list) but
>hopefully this is useful. Sorry I didn't get to it sooner.

I didn't give it a look yet but thanks for sharing.

[0] https://github.com/qgis/QGIS-Documentation#building-the-documentation-using-paver
[1] https://github.com/qgis/QGIS-Documentation#building-the-documentation-using-windows-minimal-setup
[2] https://docs.qgis.org/testing/en/docs/documentation_guidelines/first_contribution.html

Regards,
Harrissou

>
>Best wishes,
>Nick.
>
>On Thu, 17 Oct 2019 at 14:57, DelazJ <delazj at gmail.com> wrote:
>
>> Hi community,
>>
>> I read this morning news on docs and still not sure I understand the
>next
>> step but there's a recurring message I read and would like to
>explore.
>>
>> Le jeu. 17 oct. 2019 à 02:44, Nathan Woodrow <madmanwoo at gmail.com> a
>> écrit :
>>
>>> Hey all,
>>>
>>> [snif]
>>> I personally find some of the technical issues as quite a blocker
>for
>>> people to help.  It's what stops me most of the time and I'm
>conformable
>>> with the tools, last time I tried on Windows I just gave up because
>it was
>>> too much work and I only have limited time these days.
>>>
>>
>> Nathan, can you elaborate a bit on this please? How long ago did you
>> experience this?
>> QGIS-Documentation is a git repo so the usual git commands/software
>and a
>> text editor are enough to use it locally. But you can also only use
>your
>> browser and a github account, the same way you can do with QGIS repo.
>So
>> I'm a bit lost when technically skilled people mention the doc
>complexity.
>> (don't take it as a criticism...not my feeling at all! I really want
>to
>> know. and you are not the first person I read this from.)
>>
>> And because most of us are not developers, we've spent some time to
>shape
>> a doc contributor step by step (
>>
>https://docs.qgis.org/testing/en/docs/documentation_guidelines/first_contribution.html)
>> to reduce the learning curve for beginners and add some other stuff
>(eg
>> trying to WYSIWYG in Github preview, direct link between source file
>and
>> html pages, reviewing build instructions...).
>>
>> For long time now, there's an assumption that QGIS documentation
>issues
>> are related to the lack of contributors (obviously it's part of), and
>the
>> lack of contributors is itself mainly due to a high level of
>requirements
>> to step in (which I'd really like to get metrics/feedbacks on).
>> So I wonder if these observations would still be relevant and if we
>do not
>> continue to convey the old feelings. I think we can improve the
>situation
>> but without knowing what would be the blockers and if they are on
>Docs
>> management side, it'd be hard to do.
>>
>> So please speak up and tell us what is hard to do and let's see
>together
>> how we could improve it.
>>
>> Regards,
>> Harrissou
>>
>> _______________________________________________
>> 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

-- 
Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.