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

[matteo]

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 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.

> 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.

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).

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

Cheers

Matteo