[SeasonOfDocs] The Good Docs Project - next steps

Wed Jun 26 17:55:56 PDT 2019

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/20190626/f47b2bd6/attachment-0001.html>