[SeasonOfDocs] The Good Docs Project - next steps

Mon Jul 1 13:00:42 PDT 2019

Thanks Cameron! (resending now that I'm on the SOD list ..)

Hi folks, I'm Erin, I've been at Google since this past October, working on
templates to help developers create documentation for their open source
projects. In my non-Google life I run Wordnik.com (a 501c3 nonprofit that
is the world's biggest dictionary) and was previously editor in chief for
American dictionaries for Oxford University Press, where I also was an
acquiring editor for trade nonfiction language titles. I've published
several non-dictionary books, including a novel, and intermittently blog
about my sewing hobby. For fun, I run the Semicolon Appreciation Society
(which involves mostly giving out Semicolon Appreciation Society stickers).

I am very excited about The Good Docs project -- while researching docs
templates for open source, I've seen that there are lots of small
collections of templates (usually for readmes and contributor information)
but after that interest seems to die off. I think a bigger group with lots
of different use cases could put together a broader set of templates for a
wider audience as well as creating general good-docs guidance!

Also, as a mostly self-taught developer I selfishly want more and better
documentation in the world so I can get better too. :) I've been involved
with the OpenAPI (the spec formerly known as Swagger) for a while and am
particularly interested in API documentation.

At this point I know I just want to be involved since there's so much that
seems to overlap with my Actual Job, and I'm happy to see where the gaps
might be and how I might be helpful in filling them!

Thanks for including me!

Erin

On Sun, Jun 30, 2019 at 1:26 PM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> Erin, you've been included in the invite to this meeting. Why don't you
> start by sending a brief email to this list to introduce yourself:
>
> Who are you? What is your interest in TheGoodDocsProject? How would you
> like to be involved?
> On 29/6/19 4:22 am, Riona Macnamara wrote:
>
> Another thing to consider is providing resources that support writers and
> other documentarians in their careers. For example:
>
>    - Guidelines on how to measure and communicate the value and impact of
>    your documentation work:
>       - Reporting templates
>       - Guidelines on using and interpreting Analytics data (etc.)
>    - Doc sprint in a box
>    - Doc plan templates
>    - ...
>
>
> On Wed, Jun 26, 2019 at 8:56 PM Stephanie Blotner <sblotner59 at gmail.com>
> wrote:
>
>> Adding on to these ideas, I think a combination of the following will be
>> most effective:
>>
>>    - *Excellent examples* that follow the best practices (which aligns
>>    with the development practice of looking at a real-world working example)
>>    - *Templates* that make best practices easy to implement (prevents
>>    the blank page anxiety <https://gifimage.net/blinking-cursor-gif-3/>)
>>    - *Guidance about how to uplevel your docs* (for example, it's hard
>>    to write task-based docs when you haven't identified your audience or
>>    thought about what the tasks in the workflow are)
>>
>>
>> I'd be curious to collect/see data about open source developer interest
>> in "how to write good docs" training. Starting with examples and templates
>> is a quick win.
>>
>> On Wed, Jun 26, 2019 at 2:20 PM Riona Macnamara <rionam at google.com>
>> wrote:
>>
>>> +Erin McKean <emckean at google.com>
>>> Adding Erin McKean, who is doing a lot of work around documentation
>>> guidelines and best practices for open source projects at every stage of
>>> the project lifecycle.
>>>
>>> Sorry for brevity - have been in meetings continually
>>>
>>> On Wed, Jun 26, 2019 at 3:26 PM Cameron Shorter <
>>> cameron.shorter at gmail.com> wrote:
>>>
>>>> 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 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.
>>>>
>>>> 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> 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
>>>>>
>>>>> --
>>>> Cameron Shorter
>>>> Technology Demystifier
>>>> Open Technologies and Geospatial Consultant
>>>>
>>>> M +61 (0) 419 142 254
>>>>
>>>> _______________________________________________
>>>> SeasonOfDocs mailing list
>>>> SeasonOfDocs at lists.osgeo.org
>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org
>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>
>>
>>
>> --
>> Stephanie Blotner
>>
>> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> M +61 (0) 419 142 254
>
>

-- 
Erin McKean | Developer Relations Program Manager, Open Source Strategy |
emckean at google.com | she/her
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190701/6b44bc8c/attachment-0001.html>