[Qgis-community-team] [Qgis-user] [Qgis-psc] User question of the month

[Cameron Shorter]

On 17/10/19 11:44 am, Nathan Woodrow wrote:
> I think we have to be very careful taking the results of a limited 
> survey and making major changes to the project.   It's a sample set 
> but only a very very small sample set.
> There has been a bit of talk around the documentation but reducing the 
> efforting is the wrong way to go and I don't think we should support 
> that move as it will just lead to no documentation which is how we 
> started.   This is a problem for even large enterprise companies so we 
> will not find a quick fix or one that works right 100% of the time.

I have quite a few thoughts to add to this thread, but probably won't 
have the bandwidth to give it due attention for a few weeks.

But I think it is worth extending Nathan's comment here by referencing a 
highly regarded article in Tech Writing circles from Daniele Procida 
titled:  What nobody tells you about documentation. 
https://www.divio.com/blog/documentation/

Key message:

/There is a secret that needs to be understood in order to write good 
software documentation: there isn’t one thing called documentation, 
there are four. They are: /

  * /Tutorials, /
  * /How-to guides, /
  * /Explanations and /
  * /Technical references. /

/They represent four different purposes or functions, and require four 
different approaches to their creation. Understanding the implications 
of this will help improve most software documentation - often immensely./

I'd suggest that the metrics we see about people using StackExchange 
answers is that they are solving goal oriented problems (which fits into 
the How-to guides section). It is good and we should encourage its 
continued use. However all the other documentation types are very 
important to users at different times in their development journey.

//

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20191022/7880b445/attachment.html>