[SeasonOfDocs] The Good Docs Project - next steps
Cameron Shorter
cameron.shorter at gmail.com
Sun Jun 30 05:08:27 PDT 2019
Hi Kyle,
It is great to hear that you have generated so much interest for the
Documentation Compendium. It shows there is a lot of interest out there.
If you are around, it would be good to discuss with you tomorrow in the
#plan channel on https://thegooddocs.slack.com
<https://thegooddocs.slack.com/messages> at say
https://www.timeanddate.com/worldclock/meetingdetails.html?year=2019&month=7&day=1&hour=10&min=0&sec=0&p1=240&p2=44
On 30/6/19 10:12 am, Kyle Lobo wrote:
> Hey guys,
>
> This is Kyle Lobo, creator of The-Documentation-Compendium
> <https://github.com/kylelobo/The-Documentation-Compendium/>. I've only
> recently been enlightened about TheGoodDocsProject and I'm excited to
> be a part of it.
>
> I've gone through all the mailing lists concerning the project, and
> while I am fully supportive of starting the project from scratch, one
> key benefit of joining and expanding my repo (or any other repo) would
> be that it has over 2,500 stars, 20,000 views, and 8,000 unique
> visitors over the past month. Since my repo revolves around
> documentation templates & personal tips, these are people who visit
> the repo specifically for this purpose.
>
> This helps in getting a push from the get-go. The only drawback to
> this is the fact that currently my repo is very basic and lacks structure.
>
> On Sat, Jun 29, 2019 at 1:06 PM Cameron Shorter
> <cameron.shorter at gmail.com <mailto:cameron.shorter at gmail.com>> wrote:
>
> 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 <mailto: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
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto: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/20190630/4e4730cf/attachment-0001.html>
More information about the SeasonOfDocs
mailing list