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

[Tim Sutton]

Hi

> On 24 Dec 2015, at 15:55, Richard Duivenvoorde <richard at duif.net> wrote:
> 
> Hi PSC/Community,
> 
> Because I think we should attract more people to write documentation for
> QGIS, I thought we should make it easier to fix/write docs.
> 
> My idea: let's keep our rst framework, but do the editing/viewing in
> Github..
> 
> First: look at the following two examples:
> 
> [0]
> https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md
> 
> and
> 
> [1]
> https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst
> 
> As you can see the first one is immediately readable (and more editable)
> in Github.
> We have (I think from our Latex roots) a lot of extra styling
> directives/stuff in our docs. It looks like this now:
> 
> [3]
> http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html#the-vector-properties-dialog
> 
> I propose and tested the following:
> 
> - move images from resources into an images directory in the source
> folder, see
> [4]
> https://github.com/qgis/QGIS-Documentation/tree/master_github_e/source/docs/user_manual/working_with_vector
> 
> - remove all the :guilabel: :menuselection: and other directives to make
> it easier to edit/view in Github
> 
> - get rid of all/most of the image/icon shortcuts (needed for inline
> images) from source.conf and put them in the source file where they are used
> 
> - remove substitutions like |qg| (for QGIS) and |nix| (for linux icon).
> It clutters the source as seen on Github.

Just bouncing the idea around: If we follow all this logic surely it is better to switch to Markdown which is a lot more mainstream and simple to pick up and use because of its cleaner syntax? I guess with Markdown we lose the advantage of RST that  we do have: richer syntax cross referencing, multi-chapter support, translation support etc. ? Which of these are we still planning to keep?


Regards

Tim


> 
> I branched docs and changed one file, look at the Github preview now:
> 
> [6]
> https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst
> 
> As you can see it is the same file as the rst above [1], but here you do
> not see all the :xxxx: directives, you see the images etc. Hopefully
> much easier to add or fix a paragraph here.
> 
> I did not yet move all the image substitutions but if you put those IN
> the source file and point to the local image dir, you see them also in
> Github.
> 
> An example local build here next to a classic build:
> http://i.imgur.com/SjSC94N.png
> 
> I also build the pdf. Because style directives like :guilabel: also are
> followed by text in `back quotes` it still gets a special styling:
> italic in pdf and 'cite' in html
> So the stuff that is now bleu in html can for example be made italic or
> bold easily.
> 
> So should I make a QEP for this.
> Should I just GO?
> Do people REALLY miss the extra styling?
> 
> Otto what do you think?
> 
> 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!
> 
> Parts of it can be automated, as nobody has recent translated images
> there is not so much work in resources directory.
> I think we should start with the User Manual first.
> Then Python Cookbook, then Training Manual..
> 
> Regards,
> 
> Richard Duivenvoorde
> 
> PS, part 2 of all this is to fix some styling in the sphinx templates:
> remove bootstrap so hopefully it is easier to use docs in Webkit-widgets
> again (an early attempt in processing failed, I think because bootstrap
> uses to much javascript magic to make content responsive)..
> 
> 
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-psc

—





Tim Sutton

Visit http://kartoza.com <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
Tim is a member of the QGIS Project Steering Committee

Kartoza is a merger between Linfiniti and Afrispatial

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20151227/a63981e1/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: KartozaLogo160x66.png
Type: image/png
Size: 9324 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20151227/a63981e1/attachment.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20151227/a63981e1/attachment.sig>