[SeasonOfDocs] The Good Docs Project - next steps

Sun Jun 30 12:37:44 PDT 2019

Sounds good.

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

> Hi Kyle,
>
> It is great to hear that you have generated so much interest for the
> Documentation Compendium. It shows there is a lot of interest out there. If
> you are around, it would be good to discuss with you tomorrow in the #plan
> channel on https://thegooddocs.slack.com
> <https://thegooddocs.slack.com/messages> at say
> https://www.timeanddate.com/worldclock/meetingdetails.html?year=2019&month=7&day=1&hour=10&min=0&sec=0&p1=240&p2=44
>
>
> On 30/6/19 10:12 am, Kyle Lobo wrote:
>
> 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
>>
> --
> 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/20190701/c7f2180b/attachment-0001.html>