[SeasonOfDocs] The Good Docs Project - next steps
Cameron Shorter
cameron.shorter at gmail.com
Sat Jun 29 00:35:51 PDT 2019
Thanks Felicity, your message arrive just as I was sending mine (I
linked to your new doc).
I've connected with people from The lone Writers Guide and The
Documentation Compedium. Haven't yet connected with people from the
WriteTheDocs guide.
On 29/6/19 5:17 pm, Felicity Brand wrote:
> 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
> <mailto: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:
> 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
>
> _______________________________________________
> 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
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
--
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/20190629/dda93762/attachment-0001.html>
More information about the SeasonOfDocs
mailing list