[SeasonOfDocs] The Good Docs Project - next steps

[Felicity Brand]

In the interest of starting discussions, here goes:

I think articulating the goal is really important, as is defining our
audience. This is going to drive everything.



I've briefly reviewed the excellent resources that already exist that
people are pointing us to and my first reaction is that:



   - We should start with the assumption that good docs are good. We don't
   need to bend over backwards articulating why.
   - We don't need to train people *how* to write good docs.
   - We just provide really excellent templates and guidance on how to
   apply them.

That is going to be the most useful and the TL;DR option for folks who have
a messy open source project and want to bring it up to scratch. They're
already motivated to improve their docs.


We could point people to other resources if they want to dive deeper into
the whys and hows.



Things like clarity, consistency, etc (the 5 C's) is something that most
good tech writers know, so why do we need to articulate this again? Are we
teaching folk to write? Give a man a fish and you feed him for a day but
teach a man to fish and you feed him for a lifetime. Are we teaching people
to fish? I wouldn't have thought so... I think we're just giving people
fish templates. OR, to strangle the metaphor further, giving people a baited
 line in a barrel full of fish. So they are far more likely to succeed
without having to learn to fish in the first place.


So that's my first reaction. Happy to discuss further and I can't wait to
see what everyone else thinks!


Cheers

Felicity

On Tue, Jun 25, 2019 at 10:22 PM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> I'm feeling pretty special to be amongst a bunch smart tech writers who
> are keen create a "writing templates" project (and a quite a bit more).
>
> Here is what I suggest we do next:
>
> 1. Over the next few weeks, lets start discussions on this
> SeasonOfDocs at lists.osgeo.org email list.
>
> 2. Between us, lets articulate our vision. I suggest we bounce ideas
> around on this list, and start collecting them into a Google doc that we
> collectively edit. I've been getting inspired by each of you on what this
> vision might be. We should think big, but make sure our first goals are
> very achievable.
>
> 3. Are there any existing projects which we should join instead of
> starting our own?
>
> * Riona pointed to this project:
> https://github.com/kylelobo/The-Documentation-Compendium
>
> * Stephanie pointed to:
> https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide
>
> Does anyone know the people behind these projects? We should reach out to
> them. I'll be interested to hear thoughts on these projects.
>
> Lets discuss on email over the upcoming week. Next week, lets aim to
> decide if we are to join an existing project or start our own.
>
> 4. I suggest we set up a meeting next week with those of us who can make
> it. Maybe:
> Location Local Time Time Zone UTC Offset
> Sydney <https://www.timeanddate.com/worldclock/australia/sydney> (Australia
> - New South Wales) Tuesday, 2 July 2019 at 8:00:00 am AEST
> <https://www.timeanddate.com/time/zones/aest> UTC+10 hours
> Austin <https://www.timeanddate.com/worldclock/usa/austin> (USA - Texas) Monday,
> 1 July 2019 at 5:00:00 pm CDT <https://www.timeanddate.com/time/zones/cdt> UTC-5
> hours
> New York <https://www.timeanddate.com/worldclock/usa/new-york> (USA - New
> York) Monday, 1 July 2019 at 6:00:00 pm EDT
> <https://www.timeanddate.com/time/zones/edt> UTC-4 hours
> London <https://www.timeanddate.com/worldclock/uk/london> (United Kingdom
> - England) Monday, 1 July 2019 at 11:00:00 pm BST
> <https://www.timeanddate.com/time/zones/bst> UTC+1 hour
> Paris <https://www.timeanddate.com/worldclock/france/paris> (France -
> Île-de-France) Tuesday, 2 July 2019 at 12:00:00 midnight CEST
> <https://www.timeanddate.com/time/zones/cest> UTC+2 hours
>
> (I can do earlier or later.)
>
> 5. A few of you were wanting to get clarifications from your organisations
> about open sourcing material. I suggest letting us know how that
> progresses. This might help
> http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html
>
> 6. If we decide to start our own project, we will need to set up web
> pages, project structure and so on. If we join an existing project, we will
> likely need to help them do some of these things. We can start in a week or
> two.
>
> Okay, over to you. Please don't be shy - share your ideas and suggestions,
> and lets get this vision nailed down.
> On 25/6/19 9:09 am, Riona Macnamara wrote:
>
> Have you seen this?
>
> 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/seasonofdocs/attachments/20190626/68532f4b/attachment-0001.html>