[SeasonOfDocs] The Good Docs Project - next steps

Wed Jun 26 14:20:09 PDT 2019

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