[SeasonOfDocs] The Good Docs Project - next steps

Sat Jun 29 17:12:18 PDT 2019

Hey guys,

This is Kyle Lobo, creator of The-Documentation-Compendium
<https://github.com/kylelobo/The-Documentation-Compendium/>. I've only
recently been enlightened about TheGoodDocsProject and I'm excited to be a
part of it.

I've gone through all the mailing lists concerning the project, and while I
am fully supportive of starting the project from scratch, one key benefit
of joining and expanding my repo (or any other repo) would be that it has
over 2,500 stars, 20,000 views, and 8,000 unique visitors over the past
month. Since my repo revolves around documentation templates & personal
tips, these are people who visit the repo specifically for this purpose.

This helps in getting a push from the get-go. The only drawback to this is
the fact that currently my repo is very basic and lacks structure.

On Sat, Jun 29, 2019 at 1:06 PM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> Thanks Felicity, your message arrive just as I was sending mine (I linked
> to your new doc).
>
> I've connected with people from The lone Writers Guide and The
> Documentation Compedium. Haven't yet connected with people from the
> WriteTheDocs guide.
> On 29/6/19 5:17 pm, Felicity Brand wrote:
>
> Hi Gang,
>
> I created a doc and invited you all to it. You should be able to invite
> others to it as well...
> I just collated the information mentioned in our emails so far - so if I
> missed anything please add it in.
>
> Cheers
> Felicity
>
> On Sat, Jun 29, 2019 at 4:22 AM Riona Macnamara <rionam at google.com> 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
>>>
>>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>
> _______________________________________________
> SeasonOfDocs mailing listSeasonOfDocs at lists.osgeo.orghttps://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> --
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190630/c7cf17ca/attachment-0001.html>