[Qgis-user] My first weekend with QGIS (documentation)

[John Hawkinson]

(I'm kind of regretting not having numbered my items instead of bulleting
them. There was some rationale, something about not wanting to seem imposing
and also that I wanted to maybe sort them before sending the email...didn't
quite work out that way...)

Thanks, by the way, everyone for being so welcoming. I'll have more to
say on harder stuff later (esp. Nathan's super-detailed reply!), but 
there's some low-hanging fruit here. Replies inline below.


Harrissou DelazJ <delazj at gmail.com> wrote on Sat, 21 Jan 2017
at 20:26:09 +0100 in <CAECJsSpRoxMDRQ7uiyb6J9XHZODTJUPDRn7c6Ycsdi2ROQCuWA at mail.gmail.com>:

> Doc writing instructions are available at
> http://docs.qgis.org/2.14/en/docs/documentation_guidelines/ and the
> team is present if needed.

Thanks. Here, have a (super-boring) pull request to correct
minor items in the documentation-writing documentation.
"It's turtles all the way down."

> > * Where the are the QGIS 2.18.3 release notes? They are not easy to
> >   find from the website. It's easy to get to
> >   http://qgis.org/en/site/forusers/visualchangelog218/index.html
> >   but that doesn't cover the "dot" releases. Other links take you to
> >   http://hub.qgis.org/projects/quantum-gis
> >   which is not so helpful, at least not directly.

> Weird, whick links sent you there?

Good question...So, the banner at the bottom of the Recent Projects
sends me to http://download.qgis.org (but it's not a clickable link, boo),
aka http://www.qgis.org/en/site/forusers/download.html
which doesn't really have much of a reference to changelogs.
The "All Downloads" link does have a link to Visaual Changelogs,
though I think that's not how I got there.

About QGIS > About > QGIS Code Branch
  links to https://github.com/qgis/QGIS/tree/release-2_18 which is not
  helpful for new users...that wasn't it.

About QGIS > About QGIS Home Page
  goes to http://qgis.org/en/site/ which prominently features 2.18 and a link
  to the Visual Changelog. That's definitely one place.

About QGIS > What's New
  doesn't talk about "dot" releases, but does talk about 2.18.

Help > Check QGIS VErsion
  has 
  "Details on changes can be found by examining the Activity in
  Redmine at http://hub.qgis.org/projects/quantum-gis"
  That's probably the path I used.

And the visual changelog link on the main QGIS webpage, either via
the About QGIS link or just by going to the web page.



> * CRS on first reference. On p.32 is the first time it talks about
...
> > Agreed again (should be easily fixed) but keep in mind that documentation
> is an iterative work, not really linear and we unfortunately do not keep
> eyes on first appearance of expressions. Maybe this is technically
> feasible.

Well, periodically somebody should sit down and read the manual
from cover-to-cover to make sure it "works." Definitely not a high-priority.

> > * Section 8.5 Blending modes doesn't put "soft light" in boldface like
> >   the others.
> >
> > Not sure I understand what you mean. Looks the same afaics.

https://raw.githubusercontent.com/qgis/QGIS-Documentation/master/source/docs/user_manual/introduction/general_tools.rst

* Soft light: This is very similar to overlay, but instead of using
  multiply/screen it uses color burn/dodge. This is supposed to
  emulate shining a soft light on to an image.

* **Hard light**: Hard light is also very similar to the overlay
  mode. It's supposed to emulate projecting a very intense light onto
  an image.

Note the lack of ** around "Soft light."


> > * Through the manual, settings are accessed via "Settings". But under
> >   OS X, you get there with QGIS > Preferences...
> >
> > I think it's also accessible through Settings menu under os x (no mac
> available right now to check).

Yes, you're right. One thing in two places is inherently a little confusing,
so maybe there's not much to do about it.

> > * Ctrl-$foo under Win/Linux is Cmd-$foo under OS X. The manual should
> >   acknowledge this somewhere, though maybe not everytime. (But maybe
> >   it should everytime? Because Macs do have Ctrl keys and they are
> >   available but do something slightly different. So...)
> >
> right! This should become a reflex for writers to not confuse mac users.

Well, it's definitely true that the manual becomes kind of ugly
when if it says "Ctrl/Cmd" everywhere. Another choice is to make
platform-specific builds of the manual. I dunno...

> > * Sec. 4.1, View Data, talks about WMS and WFS without expanding or
> >   explaining them.
> >
> > . Maybe this is an unfair criticism because it does the same for OGR
> >   and ESRI, as well as SDTS and JPEG. But none of those bother me?
> >
> > A glossary?

Well, maybe. But in practice few people are going to read a glossary,
and they can Google if they really want to know. The value of having it
on the first reference is to make it accessible with low-effort.
But it may not be worth the cost, and as I said, I'm not sure why
it botehrs me for WMS and WFS but not OGR and ESRI. Though the obvious
answer is "I know what OGR and ESRI are!"

> > * Figure 12.26: In the 2 images on that figure, it would sure help to
> > highlight
> >   visually the differences between them.
> >
> > Imho, images should be enough; if it's not obvious, then the figures are
> not good enough.

Sorry I wasn't clear. Indeed, I thought the images/figures were not good
enough. It shows two images side-by-side and the caption explains
that one has symbols activated and the other deactivated, but the
differences in the two images are subtle. I'd recommend annotating
the images somehow, like a bright blue circle around the areas that
differ, or maybe a subtler thing like dimming the image (reduced opacity)
where except for the region(s)-of-interest.

> Where's my prize?? :-)

Prize selection will depend on the number of claimants in a reasonable
period of time (so far, zero business days have elapsed), and is
probably prioritized somewhere after getting bugs filed for
appropriate issues. Unless you want you prize to be the answer to why
MySQL plugin under OS X didn't work with a weird error (seems
unlikely, you don't have a Mac), which I spent this morning figuring
out. The answer: "Build with -stdlib=libstdc++". Not very satisfying,
is it? ;)

--jhawk at mit.edu
  John Hawkinson