[SeasonOfDocs] The Good Docs Project - next steps

Wed Jun 26 12:26:23 PDT 2019

My brain dump additions to Felicity's skeleton embedded below.

Felicity, you started a google doc earlier with some of your ideas. Do 
you think we should retask it to becoming the first draft of our vision 
doc?

On 26/6/19 10:57 am, Felicity Brand wrote:
> 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.
>
We want to create a "best practices" guide and associated suite of 
templates for creating technical documentation for Open Source Software 
projects (as our primary use case). It will be almost directly 
applicable to all software projects and we should aim to cater for all 
software projects. It will be reasonably applicable to broader technical 
writing. While we should remain focused on our core audience, we should 
consider writing our documents such that they can be easily customised 
and extended into other domains.

Borrowing from Open Government design principles, we should "Do the hard 
work to make things Simple".

https://www.gov.uk/guidance/government-design-principles#do-the-hard-work-to-make-it-simple

Rather than each organisations attempting to create their own writing 
guides, lets attract the cross section of communication expertise into 
one central community. Within our community of communicators, we will 
debate and decide upon best practices for a range of documentation types.

We should capture a body of knowledge, referencing the best research and 
guides we can find. We should tailor components this knowledge to 
specific user groups. We could describe this as user stories. E.g.:

* As a software developer who needs to document my project, I need a 
template, clear writing instructions, and an example which I can easily 
adapt of follow.

* As a documentarian reviewing a developer's docs, I want guides and and 
checklists to review against.

I our next doc down from the vision should introduce the concept of a 
star rating for docs. Huge value can be gifted to projects by helping 
them get from the 1 star of "sort of covered docs" to the 2 stars of 
having a techie align docs with templates. This now frees up tech 
writers to focus on the more challenging tasks of polishing and 
tailoring existing content.

...

> I've briefly reviewed the excellent resources that already exist that 
> people are pointing us to and my first reaction is that:
>
I'm really interested to hear feedback on what is good or bad about the 
source material we have identified. Maybe create a list of our sources, 
and then comment on elements which we would want to bring into our 
master guide.
>
>   * 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.
>
Yes, and we might want to absorb and collate the other resources into 
our own dedicated sections.

We want to avoid saying "Want to learn more? Go read these 10 books, 
research papers, and blogs on the subject, and wade through tonnes of 
crap in order to find the gems. There will be a lot of value if we can 
increase the signal-to-noise ratio for all our stakeholders. (This is a 
slow burn activity).

> 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?
>
I just googled the 5 C's. Apparently there are 7.

Our first target audience are techies who are writing docs (software 
developers and software users). Many will be like me and won't know the 
5 C's, and won't need to know them if our templates are good enough.

> 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 baitedline in a barrel full of fish. So they 
> are far more likely to succeed without having to learn to fish in the 
> first place.
>
Yes, maybe it is a case of "bring your barrel of fish, we provide a 
stick of dynamite, you light the fuse."
>
>
> 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 <mailto: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 <mailto: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
>
-- 
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/20190627/b7aad4d9/attachment-0001.html>