Mastering doc reviews

Great doc reviews go beyond reviewing doc quality. It additionally assesses the author’s assessment of their writing ability. We can then right size nudges, within a safe space, to inspire the author to realise their full potential.

Mastering Doc Reviews shows how to lift doc quality across an organisation, using subtle tips and tricks to help everyone to write just a little bit better.

• Video at Write The Docs - Australia
• Slides
• Document Commenting Guide at The Good Docs Project

State of The Good Docs Project

Lightning talk summarizing the status of initiatives within The Good Docs Project.

Presented at Write The Docs - Australia and India. Source slides.

Tech Writing Patterns and Anti-patterns

This presentation summarizes a larger essay of Patterns and Anti-patterns and suggests ways to help solve the associated challenges. It is mostly based on experiences learned within volunteer open source communities. [Slides updated 2021-04] [Original slides].

Launching TheGoodDocsProject

Discussing templates

What is TheGoodDocsProject?

“Best practice templates and writing instructions for documenting open-source software, 
collated from the best ideas within the documentarian community.”

Incidentally, the templates will be directly applicable for other domains too. So far, we have draft templates for:

• Overviews
• Quickstarts
• References
• Discussions
• How-tos
• Logging
• References
• Tutorials

We officially launched our first 0.1 release at the recent WriteTheDocs - Australia conference and were honoured to have ~ 50 documentarians review our templates in a two-hour "fix-it" session.

What next?

• Over the next few weeks, we will be copying suggestions into our issue tracker.
• By ~ March 2020, we plan to publish a 0.2 release, incorporating suggestions to date.
• We hope many documentarians will join us to help improve these templates.
• And then, with a bit of luck, people will start using the templates.

Highlights from WriteTheDocs - Australia

A bunch of ideas were presented at the WriteTheDocs conference which I'd love to see captured in our templates and shared with others. These included:

Inclusivity Dave presented an amusing and informative lightning talk using sign language, presented through his (female) interpreter. He started, "You are probably wondering why I sound like a woman? I was born deaf ..." He has since volunteered to add best practice inclusivity into our templates.

Dave Parker

Including international communities Alec discussed cross-cultural and cross-language inclusivity, along with challenges and potential solutions. It will be good to see these ideas woven into our templates.

Alec Clews

Empowering writers Leticia talked in inspiring terms about practical techniques to empower technical writers. I've seen many dis-empowered technical writers and I'd love to see techniques to address this captured and disseminated.

Leticia Mooney

Psychological safety Riona challenged conventional thinking about open source communities. She discussed technical and social barriers to technical fields, and linked psychological safety, knowledge sharing and good documentation to building more egalitarian societies.

Riona MacNamara

Information architecture Elle discussed building information architectures, and avoiding social and technical biases. We have only scratched the surface of this topic in TheGoodDocsProject and more expertise is required.

Elle Geraghty

Storytelling Jon and Tim wove a compelling tag-team story about narrative in game design. If we can get technical writing to be as interesting as this, readers will absorb information more effectively.

Jon Manning and Tim Nugent

Tech Writing Workshop Sarah presented Google's internal Tech Writing 101 workshop for Developers, which Google plan to share publicly. It will be great to harmonise this with TheGoodDocsProject.

Sarah Maddox

Release Notes Alex drew inspiration from horror stories when explaining best practices for release notes. This is worth watching, just for entertainment value - but we should also be capturing these insights into our templates.

Alex Koren

The pitch Mat recorded a post-conference talk about harnessing the post-conference arfterglow (password: WTD2019). At the conference, he was leading conversations about building a business case for us all to take back to organisations explaining the value we all gain by collaboratively sharing and maintaining templates, including: Training users to become familiar with standard documentation patterns. Reducing ramp-up time for documentarians. Supporting cross-domain expertise.

Mat Walker

What next for you?

Are you inspired? Want to help writers become more effective, and by extension, help share the world's knowledge? Come introduce yourself to the rest of us at TheGoodDocsProject.

TheGoodDocsProject Fixit workshop

Are you coming to the Write the Docs conference in Sydney, Australia, 14 and 15 November? If so, I hope you will feel inspired to join our GoodDocsProject FixIt workshop.

We started TheGoodDocsProject to create best-practice templates and writing instructions for documenting open-source software. With our alpha release, we’ve created some common templates which we’d love people to test, break and improve.

Topics:
Diverse contributions encourage. We hope to cover:

• As a user or developer or writer: Try writing instructions for your favourite application based on one of our templates. Give us feedback.
• As a technical writer or information architect: Review one of our templates, try and find limitations, suggest modifications, offer sections to add, debate improvements.
• You have another idea: Let’s hear it.

Schedule:

• 5 min: Introduction.
• 30 min: Break out into groups brainstorming topic.
• 15 min: groups present back to everyone.
• 30 min: Break out2.
• 15 min: Groups present2.
• 5 min: wrapup and thanks

Logistics:

• We will have flip charts and pens for brainstorming, and
• We will use track changes and Google Docs. (Bring a laptop.)
• Source templates: https://github.com/thegooddocsproject/templates

Post Fixit:

• Join our email list or slack chat.
• Help us triage ideas into our kanban board and issue tracker.
• Contribute further.

Who are we:

• Cameron Shorter, Business Analyst by day, Open Source Developer and accidental Technical Writer by night.
• Jared Morgan, Senior Technical Writer at Squiz
• Erin McKean, Docs Advocacy Program Manager at Google
• Felicity Brand (attending remotely), Technical Writer for Google Season of Docs
• Sanket Totewar, Technical Writer and a few more things
• Others from TheGoodDocsProject

Amplifying Google's Season of Docs

Google has initiated a Season of Docs collaborative program aimed at improving open source documentation. It provides a great opportunity for us involved in open source and documentation to focus on big communication challenges.

Challenges

• Vision: Does everyone know the characteristics of good open source documentation? Does anyone know? Let’s collate research and best practices into accessible guides and templates.
• Targetted: Projects communicate with a range of personas. They have different technical backgrounds, attention spans and information needs. A range of documentation types are needed. Each requires different levels of depth, specificity, currency, narrative, personalisation, examples, and more.
• Empower everyone to contribute: Good documentation benefits from cross-disciplinary contributions: from developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. Open source documentation processes are typically set up by developers, for developers, and have a significant barrier-to-entry for others. How can we fix that?
• Attract volunteers: How can we apply our knowledge of collaborative and volunteer communities to attract documentation teams? How can we help volunteers maximise the impact and effectiveness of their contributions?
• Current and Sustainable: How can we sustainably keep documentation synchronised with rapidly evolving software? How do we help users find current material and archive outdated docs? How do we minimise maintenance?

What to focus on?

To maximise value, I suggest promoting initiatives which:

• Use and contribute to documentation best practices.
• Use templates and guides for key documentation types to help cross-domain collaboration.
• Attracts volunteers, from multiple user profiles.
• Applies multi-directional mentoring.
• Refines workflows and tools to reduce barriers-to-entry.
• Focuses on a specific initiative which tests the bounds of these ideas for a specific project and captures lessons learned.

This might involve:

• Auditing existing documentation.
• Defining a writing strategy.
• Developing or refining a specific documentation type for a project.
• Mentoring a project’s community, increasing the initiative's sustainability.
• Contributing to best practices.

If we can achieve this:

• Writer contribution impact will be maximised,
• Community writing will become more effective,
• And documentation maintenance will become more sustainable.

Further Reading

The OSGeo Foundation's focus in Season of Docs 2019:

• High impact writing tasks, targeting the greater Open Source community, OSGeoLive, QGIS and GeoNetwork.

General:

• Google Season of Docs
• Inspiring techies to become great writers

Documentation Strategy:

• What nobody tells you about documentation
• Document type definitions I’ve written before.

Research into building open source communities:

• Analysis of over 170,000 open source projects to identify success factors
• Success factors of episodic volunteering in Open Source