[SeasonOfDocs] The Good Docs Project - next steps

Fri Jun 28 11:22:24 PDT 2019

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