[SeasonOfDocs] Best practice links

[Jo Cook]

Hi All,

I've been adding a few links on good practice when writing documentation to
our ideas page at
https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Best_practice_templates.
This includes things like "words to avoid", particularly when writing
documentation aimed at new users.

For example something that has bugged me for years, but is summed up really
well in one of the links, is using words like "just..." and "simply..."
particularly when followed by an instruction to install something with npm
or pip, or create a virtual environment. These things are all
straightforward when you're familiar with the tools, but as a new user you
may need to go through several steps first to get set up with
npm/pip/virtual environments, and it's extremely discouraging if you feel
that you can't event get to stage one.

It would be good to hear from everyone about other phrases or words that we
should avoid using, and it would be even better, when we get a few more
links, to try to distil the suggestions into something that could be added
to a best practice document, almost like a checklist.

All the best

Jo

-- 
------------------------
http://about.me/jocook
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190527/12aadd5a/attachment.html>