[SeasonOfDocs] The Good Docs Project - next steps

Sat Jun 29 00:17:57 PDT 2019

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190629/5d287028/attachment-0001.html>