[Qgis-psc] Doc writing: simpler writing and styling

[Richard Duivenvoorde]

On 28-12-15 09:15, matteo wrote:
> Hi Richard,
> thanks for raising this.
> 
>> - remove all the :guilabel: :menuselection: and other directives to make
>> it easier to edit/view in Github
> 
> couldn't they be replaced by double quotes? Like  ``Settings -> SR``

Yes that is an option, but just replace the :xxx: directives with
nothing and leaving the single backticks as is makes them appear as
<cite> so we keep a way to distinguish the menu/gui names from code
(which you get when you use double backticks)

>> - remove substitutions like |qg| (for QGIS) and |nix| (for linux icon).
>> It clutters the source as seen on Github.
> 
> +1

Yeah, thougth the |nix| one is actually an inline images, which cannot
be removed unless we remove all those little 'Operation System'-icons in
the caption of the screendumps.

>> The whole plan/vision is that by looking cleaner/better in Github, it is
>> easier for people to edit/fix stuff in docs: so we have better
>> Documentation!
> +1
> and a question.. it is not a problem even for "not advanced" user to
> add/remove/edit some text in the documentation.. they just need to sign
> up in github and edit the file and then github does all the stuff
> (commit.. etc.. so the user doesn't know anything about git, terminal,
> pushing, pulling.....
> 
> but what if someone wants to add an image? is there mandatory to clone
> the repository and then handle the process with git or is there a
> "simpler" way?
> 
> I'm thinking especially for all the Processing algorithms help files. In
> a future it would be good to have some image that could explain the
> algorithm, but for a "normal user" it is not so simple..

Yep, it is still not perfect :-(
But we could always write some help texts that people should add images
into their pull request (and some text where to place the image) so
somebody pulling the the PR can add and place the image.

I'm thinking about the adagium "more eyeballs see more errors" (or so),
that if we make it easier for a lot of people to fix (small) errors, at
least we will have uptodate docs more. And off course we will still need
hardcore doc writers like you to do the heavy lifting :-)
But even writing something without images is already great. I just hope
that we will have a lot of small fixes by a lot of people...

Thanks for you response!

Regards,

Richard Duivenvoorde

PS about part 2 of my email: I found that in newer versions of Sphinx,
there is already a responsive (default) template:
https://github.com/bitprophet/alabaster