[SeasonOfDocs] The Good Docs Project - next steps
Cameron Shorter
cameron.shorter at gmail.com
Sun Jun 30 13:25:52 PDT 2019
Erin, you've been included in the invite to this meeting. Why don't you
start by sending a brief email to this list to introduce yourself:
Who are you? What is your interest in TheGoodDocsProject? How would you
like to be involved?
On 29/6/19 4:22 am, Riona Macnamara 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:
> o Reporting templates
> o 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 <mailto: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
> <mailto:rionam at google.com>> wrote:
>
> +Erin McKean <mailto: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 <mailto: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 baitedline 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
>> <mailto: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
>> <mailto: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
> <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
>
>
> --
> Stephanie Blotner
>
--
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/74cd082e/attachment-0001.html>
More information about the SeasonOfDocs
mailing list