[Qgis-community-team] Draft paper discussing QGIS docs

[Cameron Shorter]

On 28/8/19 12:56 am, matteo wrote:
> Hi Alexandre,
>
>> I think we have already identified a few limitations on QGIS
>> Documentation workflow a long time ago, but it's quite hard for us (QGIS
>> Documentation team) to move away from what we have without some kind of
>> divine intervention. In my opinion, the biggest challenge is to attract
>> volunteer people to it and keep them motivated to regularly contribute.
>> A lot has been discussed about lowering the barrier for new contributors
>> but moving away from git+sphinx is for me a "no-go". Why? Because we
>> can't manage 400+ pages of content using google docs or any other
>> WYSIWYG editor. We could move to markdown instead of sphinx, but I don't
>> think that would make people contribute more. I think we already decided
>> that, in terms of infrastructure, we will need to keep using git and
>> sphinx. So we need to teach people how to use it. There is some good
>> information here:
> I cannot agree more on this. Moving away from git+sphinx (at least git)
> would be a terrible mistake. Personally I'm -1000 on this.

I agree that we need to stick with your current git/sphinx toolset, at 
least for the next year or two.

Simplifying the tools is a universal problem for technical 
documentation. It has been raised in our GoodDocsProject community of 
documentatians. I suspect it will be addressed within 3 to 5 years by 
documentation communities. Lets wait until that happens.

But we can focus on improving newbie doc experiences at a personal 
level. Have a "community leader" reach out to every person who might 
want to help, and be proactive in helping them. (I know you already do a 
bit of this, but it should be resourced more.)

>> I don't understand what you mean by having a clear vision of what we
>> want our documentation to be. In my opinion, QGIS Documentation is quite
>> good (at least the user manual). Sure we could trim some fats here and
>> there, and determine what fits in the user manual, what should go to the
>> training manual. But maybe I am not seeing the full picture, maybe there
>> are other ways of organizing the documentation. But even if we do, we
>> still just don't have enough manpower to do it. We don't even have the
>> manpower to keep it updated! Facts are, we have 2/3 active persons
>> working on documentation "against" a couple of dozens of QGIS core
>> developers. And that leads me to a conclusion:
> again I totally agree. And let me enforce a little bit what you said
> (even if you maybe don't agre with this): documenting a new complicated
> features could be hard. Hard to understand, hard to load the correct
> data to make screenshots, hard to understand the best place in the
> documentation.
I get the impression that this message is absorbed by the community yet. 
It needs to be.
>> The same way we have moved most of QGIS development from volunteer
>> contributions to professional services done by individuals and
>> companies, the same must happen to documentation. IMHO, when a company
>> (or its client) fund a new feature, the documentation work should also
>> be included. Once the new feature is done and merged, the second half of
>> the work should be documenting it at least in the users manual.
>>
>> There should still be space for volunteers contributions, but a project
>> like QGIS can no longer rely on it only.

Yes, I agree totally with this, and it is a message that needs to be 
explained to the community and then absorbed into practice.

Define it as part of your vision, or maybe call it a manifesto.

> I see your general picture and I'm +0 on this. What I see sometimes
> happen is what Andreas already pointed out: for different reasons (wrong
> or correct, I'm not arguing this), new features are documented in other
> places than the QGIS Documentation. I don't have a proposal on this, I'm
> -1 to add links to external resources in our docs (broken links,
> different syntax, etc).

This behaviour of documenting outside of core should be called out as 
detrimental to the QGIS project and called out has bad behavior. Sure, 
add docs to your personal blog. But a feature should not be considered 
complete, and companies should not get their code patches accepted into 
the final QGIS codebase until documentation is complete, up to our 
definition of quality, which includes being reviewed by one of OUR 
nominated senior technical writers (some of whom will be available for 
hire.)

Further, there should be a paid community builder / technical writer to 
do the standard dirty work, so that volunteers can focus on their 
writing tasks that they want to work on.

Note, I can help out with crafting a manifesto in slow time.

>
> IMHO having in this precise moment more contributors could make more
> damages than benefits: we have to decide a clear workflow to follow (see
> my other mail with some proposal) so we can than encouraging new comers
> to step in and to stay with us
>
Is anyone presenting at FOSS4G about docs? Is there an opportunity to 
raise this topic amongst the greater community at FOSS4G?

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254