Finding Hidden Gems in Collaborative Communities

How do you,

• As a community leader,
• Recognize ‘hidden gems’ in a community, and
• Attract them to collaborate with you?

Image: Where's Wally World Record

The pitch

The Pitch	The Message
I've seen what you’re doing and I’m impressed.	I’m not wasting your time. I’m showing you that I’ve researched your work before contacting you. I’m demonstrating that I understand your cutting edge ideas and the value of them.
A bunch of us are pushing the same concepts to the next level.	I’m offering to amplify your research and altruistic goals through our project’s marketing channel. I’m hinting at trustworthiness, mentioning others who have already joined. This also hints at commitment and momentum. I’m offering more than I ask.
Will you join us?	I’m asking for help. You’re more likely to join if asked. Combined with hinting at how unique your skillset is, I’m appealing to your moral duty to step up. I’m inviting you to share ownership in our project.
I’m not offering riches, we’re giving away our creations. I'm not offering fame. Beyond our inner circle, most people won't know what you’ve done.	You’re intrinsically motivated. Social status and money are just a means to an end. I’m telegraphing that these principles will apply to all collaborators.
We realize this is a moonshot, and the odds are stacked against us.	Let’s be clear. Most tech projects fail. There likely isn’t a business case yet to justify what we’re doing. I’m looking for collaborators with grit; collaborators ready to tackle tough challenges. Being comfortable with failure comes with the job. Since you already work in this domain, you can judge the likelihood of success, and your ability to help the project succeed.
But if we succeed you will know, in your heart, that you have helped build something awesome for humankind.	Working for a higher purpose motivates you.
Interested?	You aren’t convinced yet. But this starts you considering possibilities. It invites conversation and a response.

Don’t use this pitch

To succeed, you will need to be genuine:

• Customize the pitch to match your values, reframed in your language, uniquely tailored for the needs of your ‘hidden gem’.
• Genuinely care about the person, their challenges, and their success.
• Behave like a ‘hidden gem’ yourself.

Then:

• Check in regularly, be a good listener and help when needed.
• Ensure psychological safety, where everyone feels safe to try risky ideas and be vulnerable in front of each other.
• Stay on task.

Who are the ‘hidden gems’?

A small percentage of people in communities are high-impact enablers. They tend to be:

• Visionary lateral thinkers, who consider the bigger picture and are open to challenging established thinking (including their own).
• Highly motivated, stepping up for hard and boring tasks when others step back.
• Generous with their time, empowering those around them.
• Humble, and quick to share credit.
• Overcommitted.
• Contagiously enthusiastic, balanced by an inner peace and self-awareness.

I believe there are ‘hidden gem’ characteristics within all of us. These characteristics surface when presented with the right opportunities.

Supporting research

‘Hidden gems’ are:

• The “captains” in Sam Walker’s The Captain’s Class - the team members who:
• Lead from the back.
• “Carry the water”.
• Have the courage to stand apart.
• Apply a low-key and democratic communication style.
• Do not quit.

• The 1% in the 90-9-1 rule for online community participation where:
• 90% of community users tend to be lurkers,
• 9% contribute a little, and
• 1% account for most of the action.
• The “self-actualized” people at the pinnacle of Maslow’s hierarchy of needs who are innovative, self-sufficient, empathetic and motivated by a higher purpose.
• The servant leaders who embrace humility, respect and trust in Debugging Teams.
• The curious, passionate, and community minded “alpha geeks” that O’Reilly media watches to predict future technical trends.
• The glue people who pick up the less-glamorous, less-promotable work that makes teams successful.
• The enabling contributors found in research on the success factors in open-source software communities, and studies on episodic volunteering.

Diverse communities

Projects are more innovative and successful when they attract a diverse community. One with diverse backgrounds, skills and perspectives that extends beyond the ‘hidden gems’ described here. Attracting and retaining this diversity requires a broader approach that goes beyond the scope of this article.

Where?

'Hidden gems’ often under-play their worth and can be difficult to recognize. Look out for people consistently sharing useful answers within a community forum, or writing insightful blog posts, or presenting on a niche topic at conference events.

Time to reach out?

Have you noticed a ‘hidden gem’ in your community? Is it time to reach out and offer to help them become more impactful?

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

Commenting guide for collaborative document reviews

After thousands of collaborative documentation reviews, from our Good Docs Project technical writers, we have established a bunch of practical tips for providing good feedback on documents. We’ve collated our collective wisdom into a commenting guide for collaborative document reviews. It includes:

• Tips for reviewers to convey useful and actionable comments, which don’t mess up the original document.
• Tips for authors, to attract useful feedback, and resolve comments cleanly and respectfully.

This guide will be useful for any teams working with doc tools which support track changes, like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab.

Thanks to the many Good Docs tech writers who helped collate and refine this guide.

Gitlab's conversation with The Good Docs Project

The Good Docs Project has been inducted as a GitLab open source project partner, and Bryan Behrenshausen from GitLab interviewed us about our project.

Open Source awards for Good Docs contributors

Congratulations to Google's Open Source Peer Bonus award winners. Winners from The Good Docs Project include:

Ophy Ampoh

Ophy Ampoh is an impactful open source techie and writer, across multiple projects.

• She co-developed a howto documentation template for The Good Docs Project.  
• She actively contributes to, and supports other writers in Good Docs weekly meetings
• She writes training material for freeCodeCamp.
• She teaches women to code in Ghana. 

Joseph Kato

Joseph is the founding creator of vale.sh, an open source grammar checker, used to check the quality of documentation against a project’s documentation style guide. The tool is well written, in a modular fashion that supports extensions.

Mengmeng Tang

Mengmeng Tang is an experienced technical writer who has been playing a lead role developing templates and writing best practices within The Good Docs Project.

• Most notably, Mengmeng has led the development of a API Reference template, researching multiple source reference documentation processes, coordinated community contributions from multiple people, and drawing it together into an authoritative source.
• She has been mentoring others.
• She has been an active contributor to other Good Docs forums and initiatives, such as our cross-template style discussion forum.
• She is regularly stepping in and helping others out.

Keystone Project - The Good Docs Project

The Good Docs Project is growing into a keystone project for software ecosystems.

What’s a Keystone Project?

In architecture, a masonry arch cannot be self-supporting until the keystone is placed. This stone locks together the whole structure.

The concept is also found in ecology. A keystone species is an organism that helps define an entire ecosystem - and it has a disproportionate influence on the ecosystem around it. Bees are a keystone species. Without bees, flowers don’t get pollinated, plants don’t reproduce, animals starve, and the ecosystem collapses.

In the technology domain, Git can be thought of as a keystone project. Its version control underpins many software projects, meaning it has a disproportionate positive impact on the software ecosystem.

Is documentation disproportionately impactful?

Yes. Time and again, surveys call out documentation quality as a key criteria to:

• Ensure developer productivity,
• Ensure product quality, and
• Attract a user base.

For instance:

Developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats.—The 2021 State of the Octoverse, Github

… Find more stats in the Docs Fact Pack.

What is good documentation?

Good documentation provides:

Just enough info,
When it is needed,
To support a specific action,
At the quality required.

Getting this balance right is both an art and a science. The Good Docs Project explains how, by providing best practice templates and writing instructions for documenting open source software.

Are we there yet?

Not quite. We will be a keystone project when:

• Open source surveys stop reporting poor documentation as a key developer gripe, and
• People attribute documentation improvements to The Good Docs Project templates and processes.

Signing off from Google

It's been a great three years at Google. So many opportunities to do something meaningful, to learn, to be impactful.

Chromebook requirements team

It's been an exciting journey maturing requirements management, traceability, testing. It's enabling chromebooks to scale. We have a talented team - I'm looking forward to hearing continued great things from you.

Cross-Google requirements engineering folks

It's been wonderful to see the cross-pollination of ideas between projects. We have learned from your collective wisdom. Will be great to see this continue.

ChromeOS in general

I've worked 1:1 with many hundreds of you, polishing requirements and documentation, and have been very proud of what we have achieved together. Keep up the good work.

Chromebook Docs & Training team

How far we've come in lifting our processes and tools and documentation quality. Still plenty to do. Great to have your expertise to realize the future challenges.

Sydney Chromebook team

Thanks for your encouragement, for your personal face-to-face friendships, for being my lunch buddies, for your collaboration in developing requirements.

Google Tech Writing community

I'm going to really miss tapping into such a depth of wisdom embodied within Google's tech writing community. I'm particularly disappointed to be leaving just as a cross-Google tech writing initiative is kicking off. It will be great fun and has great goals. I'm now extra-hopeful that some of you will collaborate externally, so us Ex-Googlers can join in. I hang out in The Good Docs Project.

Green AU team

We have such a great opportunity to amplify Green ideas through Google, and to bring international Googler Green ideas and technology to Australia.
And Australia is ideally positioned to become an international leader in Green energy, something we can tap into and amplify within Google.
I’m hopeful my future employment is in this green space, and I get to work with you again from the outside.

Geo folks

Great to see folks embracing that:

1. We have a misaligned mapping problem due to hacks which ignore tectonic plate motion.
2. The problem is solvable, with easy quick wins, starting with storing coordinates in a static datum.

I look forward to hearing progress in this area.

Why leave?

Google’s been forced to realign priorities and is cutting 12,000 roles “across Alphabet, product areas, functions, levels and regions”. My Sydney team is one of those targeted.

Would I come back?

• Yes. I've met so many interesting, genuine and passionate people in Google, thinking bigger than just their day jobs.
• Yes. Google provides great opportunities to amplify personal contributions to the world.
• Yes. It's hard to beat Google's great lunches.

What's left for Google to get better at?

• We're good, but sometimes we should remind ourselves that awesomeness exists outside of Google too. It's worth looking.
• Maybe collaborate more. Yes, it costs more in the short term, but it's usually worth it for the long term play.
• Maybe ask if our internal initiatives can help the world, as well as just Googlers. There's usually a good business case.
• And if really brave, read Praveen Seshadri’s essay The maze is in the mouse.

What's next for me?

• There are some wicked challenges in the Green space, and Australia has the opportunity to become a green energy leader. I'd love to apply my skills here.
• We've been maturing the tech writing disciple within The Good Docs Project. It would be nice to continue this.
• And I'm open to picking up in the Geospatial Business Analysis, or Systems Engineering spaces again too.

This article is also published on LinkedIn.

--

Cameron Shorter,

Senior Technical Writer, Google's ChromeOS Platforms

Meet a Google Tech Writer

Yep, I'm one of the profiled Google tech writers:

Cameron's story

I was surprised to wake one morning and realize I’d become a writer.

My good science and sub-optimal English school marks led me to pursue a software engineering career. (Who needs to write when you’re a good programmer? Right?)

Outside of work, I leaned into my greenie ideals and helped build a bicycle activist movement: Thousands of yahooing cyclists riding through city peak hour traffic, publicity stunts, chats with the police, media interviews... Of course, my software career wasn’t being advanced by these extra-curricular activities.

Over time, my day job gradually moved from engineer to business analysis to sales support, to technical communicator, and oops, … I’d become a technical writer. How did that happen?

Well, it turns out that in knowledge economies, businesses value people who can explain technical concepts clearly, efficiently, and effectively. The activist communication skills I’d learned, merged with my engineering background, were useful after all.

And as an added bonus, I really enjoy the communication challenges, the breadth of work, and the impact I can offer teams. You might, too?

Requirement writing

•  "When [condition] the [device] MUST [do something]."

It's surprising how many ways we can get this pattern wrong. This presentation walks through the requirement-writing-guide used by Google Chromebook engineers, and open sourced into The Good Docs Project. It covers:

• Business drivers behind requirements management.
• Writing rules to follow.
• Broader systemic challenges to be faced.

It draws upon engineering standards and best practices.

• Slides (cleaned for public release).
• Video (23 mins).

Open Source awards for Good Docs contributors

Congratulations to Google's Open Source Peer Bonus award winners. Winners from The Good Docs Project include:

Felicity Brand

Felicity Brand has been an incredibly impactful contributor within The Good Docs Project.

• She is one of the project’s founding members, and an active contributor to the Project Steering Committee.
• She regularly comes up with innovative and practical ideas, usually backed by deep background knowledge.
• She is regularly supporting others, focusing on key areas that need help. Most recently she has been playing a lead role developing a Content Strategy, Website Architecture, and development of project blogs.
• When boring but important things need to get done, Felicity is regularly stepping in to help out.
• And her fun, supportive and encouraging style is contagious. It makes those around her want to help.

In Felicity's words:

“I’m very pleased and proud to receive a Google Open Source Peer Bonus award. I was nominated for my contributions to The Good Docs Project where we are creating technical writing templates to help other projects create high-quality documentation. I’m passionate about the work we’re doing there, and have been hanging around the project since its inception in 2019. This is a friendly, inclusive community creating a safe space for folk to dip their toe into open source. We are global, and new folk are always welcome.”

Bryan Klein

Bryan Klein is a technical wizard when it comes to setting up documentation based infrastructure. He has been setting up or advising on much of the infrastructure behind The Good Docs Project, a project developing templates, processes and tools to help developers write great documentation.

• He is one of the main drivers behind a “Doc tools easy button”, a bold initiative to build the toolchain a for a docs website based on templates from The Good Docs Project.
• He is an active contributor to the Project Steering Committee.
• He is fun, supportive, encouraging, is quick to jump in and help others when they get stuck. He is one of the key people behind our unofficial tech-help channel

In Bryan's words:

“I've been actively working on open source projects since my time at NIST with the FDS project starting in 2006. More recently with The Good Docs Project (TGDP) since 2020. It's been a very rewarding experience to contribute to TGDP, with such an amazing diversity of participants, perspectives and interests involved. To be given recognition through the OSPB program was a pleasant and unexpected surprise. While it's not at all what I am participating in the project for, it feels great to have someone else in the project bring my name up for this award. Thank you to TGDP and to Google for this honor.”

Aaron Peters

Aaron Peters has been bringing his project management expertise to The Good Docs Project.

• Aaron has been a long term contributor to the project, and is an active member of our Project Steering Committee (PSC).
• He coordinates our Request of Comment (RFC) update process.
• He has led the development of our baseline development and release process.
• And he has been researching and setting up the supporting tool chains.

All his foundational work is setting up our project to achieve quality at scale.

Serena Jolley

Serena Jolley deserves recognition for generously sharing her deep experience as a User Experience (UX) designer with The Good Docs Project.

• She established a heartbeat in our previously dormant “Chronologue” working group – a group creating a fake project which our documentation templates will create examples for.
• She’s played a vital role creating well-thought out wireframes for the fake project.
• She shares her knowledge with her teammates by being transparent and explaining her methodology, and has specifically mentored a junior UX designer along the way.

Without Serena, this working group wouldn’t have achieved its current momentum.

Ian Nguyen

Ian's been working within our Chronologue working group, which is creating a fake project which our documentation templates will create examples for.

• Ian is the craftsman who has been building the fake product our group wants to document.
• He has been designing and implementing an API to retrieve data for events.
• He has turned wireframes into code, and he has been building a tangible web experience for the Chronologue project.
• Without his creativity and technical aptitude, we would not have a “fake” product to document.

Tina Lüdtke

Tina was ineligible for the Open Source Peer Bonus, as she was hired by Google as an employee. Instead she was awarded a Google Peer Bonus.

Tina has led our “fake example project” makes excellent contributions to the Content Strategy, Blog, and Book Club groups, and is an active contributor to the Project Steering Committee.
Check her post 6 Resources for Starting Your Journey Into Docs.

When to call in us tech writers

In a knowledge economy, effectiveness depends upon transferring ideas between people.

Technical writing is the art of optimizing the communication pipes.

Good documentation provides:

Just enough info,

When it is needed,

To support a specific action,

At the quality required.

This presentation highlights the key principles of technical writing, and when to call in us technical writers.

• Slides.
• Video (6 mins).

Open Source Peer Bonuses for Good Doc Templateers

 Congratulations to five templatateers from The Good Docs Project for your Open Source Peer Bonus award from Google.  This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.

Gayathri Krishnaswamy, Chris Ganta and Nelson Guya

Gayathri, Chris and Nelson have been peer-writing open source documentation templates within our EMEA-APAC working group. This includes:

• Deep research into “What is a good quickstart document”.
• Established a quickstart template and associated guide for documenting open source projects.
• Projecting their writing expertise into the external OSGeo-Live open source project.
• Establishing and describing "peer writing". Look out for their talk about their experience at the upcoming Write the Docs conference: Peer writing and beyond - An experimental approach to a sustainable open-source projects.

Notably call outs:

• As well as doing a lot of the research, Gayathri has managed the copying of docs from Google Docs into the github repository.
• Nelson initially worked out the OSGeo-Live documentation pipeline, and then mentored Chris and Gayathri in getting started.
• Chris did a lot of the group coordination, and has delivered an excellent presentation on the peer writing strategy that the group developed, laying foundations for how it can be replicated.

Carrie Crowe

Carrie has grown into a key role in within The Good Docs Project:

• She’s  head of the content strategy team, driving the project contributors to frame their work in terms of understanding our user bases, accounting for where individual elements of our project need to live.
• Specifically, in the last year she’s helped the project clarify its scope and focus, with the ideals of providing education to developers needing to write docs, templates for different types of docs, systems for deploying docs, and related doc subjects. That’s all thanks to her stepping in as a product manager to organize a big group of volunteers, alongside her technical writing skills used in article and template contributions.
• In recognition of her work, she's recently accepted a co-chair role of The Good Docs project.

Deanna Thompson

Deanna Thompson is an experienced technical writer who plays an impactful role within The Good Docs Project.

• She done extensive research and community consultation to build a template for writing tutorials that developers can use.
• She continually provides insightful feedback to templates others develop, showing leadership and mentorship our team greatly benefits from.
• She's been playing a lead role in establishing training for using git for tech writers within our project.
• And in recognition of her work, she has recently accepted a role on the Project Steering Committee.
• She’s certainly raised the bar on what we hope to get out of contributors!

My Open Source Docs addiction

 

Why am I addicted to open source docs?

• "Giving back" adds extra meaning and purpose to my life.
• It's impactful.
• I can tackle wild moon-shot ideas.
• I can choose to do-it-right over short-termism.
• I am often working on the cutting edge.
• I can choose morals over profits.
• I get to collaborate with a community of like-minded souls.
• It’s a fun, safe and engaging way to learn, and looks great on a resume.
• The world desperately needs doc heros, and as a tech writer I'm uniquely qualified to help.
• I've uncovered my alter-ego:

Version 1.0 of this lightning of this talk was presented at an internal tech writers event in January 2022, and a tweaked 2.0 was presented at Write the Docs Australia, December 2022.

• Video
• Slides

Defining good

Within non-trivial technical projects, it helps to have a common language to describe "good":

• It enables cross-feature comparisons and prioritization.
• It facilitates conversations between stakeholders, business and developers.

This page suggests a feature quality scale, along with how it can be applied.

Quality scale

A quality scale can be applied to:

• Business goals, stakeholder needs, features, quality, schedule, maintenance, and more ...

	User experience	Description	Requires
Qx	Over-deliver	* Functionality cannot be noticed or used by the user.
Q5	Delight	* Anticipate user desires, and provide it.	* Understand the user’s desires and passions.
Q4	Impress	* Anticipate user unanticipated needs, and provide it.	* Analyze the user behaviors and needs. * Understand the product capabilities. * Establish critical user journeys.
Q3	Satisfy	* Meet user’s known wants.	* Listen to the user’s asks.
Q2	Underperform	* Under specified or poorly implemented. * User experience includes many micro-frustrations.	* Meet purchasing authority’s specification. * Cost saving implementation. * Minimal testing.
Q1	Not practically functional	* While the product “works” the experience is so poor that the user chooses to use something else if available.
Q0	Broken	* Functionality doesn’t work at all.

Possible quality scale

Quality categories for each feature

For each feature, a project can define quality categories.

Feature	Delight	Impress	Satisfy	Underperform	Not practically functional	Broken
On/off button			Works			Fails
Waterproof to		> 100m	> 10m	> 1m		< 1m
Uptime	> 99.999%	> 99.99%	> 99.9%	> 99%	> 90%	< 90%

Example quality criteria

Note: Many features won't need the full scale.

Phase exit criteria

The importance of each quality criteria will vary depending upon:

• Different products.
• Different features.
• Different development phases: alpha, staging for test, production/stable release.

Phase: Alpha release

Feature	Priority	Should	Must	Error tolerance
On/off button	P1	Satisfy	Satisfy	Satisfy
Waterproof	P3	Impress	Underperform	Broken
Uptime	P2	Impress	Satisfy	Underperform

Example phase exit criteria

As requirements

The criteria can be converted into traditional requirements:

The device	should	be waterproof to 100m.
The device	must	be waterproof to 1m.

Example requirements

Bug severity levels

Terminology from the quality scale can be aligned with bug severity levels. Severity can be driven by impact to the user, or impact to the business.

Severity	User Impact	Business Impact
S4 Trivial	* P3 feature underperforms	* Person days to fix.
S3 Minor	* P3 feature is broken * P2 feature underperforms	* Person weeks to fix.
S2 Major	* P1 feature is broken, with work-around * P2 feature is broken, no work-around	* Person months to fix.
S1 Critical	* P1 feature is broken. No work-around.	* Upcoming releases blocked until fix provided.

Example severity scale

Open source peer bonuses

 

Congratulations Alyssa, Angelos and Aiden for your Google's Open Source Peer Bonus award.  This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.

Alyssa Rock

Alyssa has played a pivotal role in growing and expanding, The Good Docs Project. She has been doing this by:

1. Being an excellent technical writer, prolifically writing quality material for the project.
2. Reaching out at conferences and related events, advocating for the project, and attracting scores of new contributors.
3. Pro-actively helping establish a very supportive and inclusive culture, leading by example, being incredibly warm and encouraging in helping to onboard people, and writing our code-of-conduct.
4. Stepping up to do much of the grunt work to establish community processes.
5. Doing the many other small things that help make an open source project successful.

Angelos Tzotsos

Angelos has been a lynch pin contributor to many of the geospatial open source projects. Most notably, he is one of the primary coordinators of the OSGeo-Live linux distribution of open source geospatial software, supporting the 50+ projects represented to get the software up to scratch and compiling on the distribution. He is very competent, always humble, very wise, always supportive of others, and very effective at building open source communities. Notably, he has been voted onto the board of the Open Source Geospatial Foundation.

Aidan Doherty 

Aidan has been a steady and reliable contributor to The Good Docs Project, taking on core background tasks, like community building (kicking off an unofficial welcoming committee for new members), and setting up a base template working group (from which all of the rest of our project templates will depend.) He takes on the unglamorous but important work which makes an open source project successful.

Timeless documentation

Big Ben clock

Maintaining docs for an evolving software baseline is a constant pain for us technical writers. I'm often helping developers remove time based language from docs, and was surprised that I couldn't find best practices on how to apply this.

So we've added a timeless documentation section to the Google developer documentation style guide. Timeless documentation is documentation that avoids words and phrases that anchor the documentation to a point in time or assume knowledge of prior or future products and features. So while it is okay to reference "a new feature" in news article; "latest" or "new" shouldn't be used in reference docs. The content becomes outdated soon after publication.

You can read more about it in the Google developer documentation style guide.

Doc templates workshop

The Good Docs Project is about to run a series of one hour workshops to brainstorm:

• What constitutes a good doctype template?
• How should we capture and present best practices in our base template docs?
• Which templates should be worked on next?

When

We'll start around March 17, 2021. If you’d like to contribute, please vote for your preferred time slot and help us understand how many people will attend: Doodle poll.

Feedback will be used to update our base template, and set the direction for future template development.

Sessions

Pre-reading:

• To contribute meaningfully you should read our base template docs, and be ready with questions or suggestions.

Session 1: Overview

• Walk through of our current base doctype template
• Explain logic behind each section
• Field questions
• Identify topics to discuss in future sessions

Session 2,3: Topic discussions

• Deep dive into topics identified in session 1
• Absorb actions to update the base template
• Volunteers to test theories by starting to write a template

Why participate

Participate if:

• You are keen to help shape best practices in doctype templates.
• You’d like to adopt a basetype template.
• You have expertise, bandwidth and commitment.

Background

To date:

Within The Good Docs Project we are creating best practice templates and writing instructions for documenting open source software.

In our first release in 2019, we’ve created 0.1 core templates, based on insights from multiple senior tech writers. These are quite good, but in the interim we’ve been improving these templates, building up processes, and refining our thinking about what makes a good template.

This has accumulated into our current base template docs. As of March 2021, these docs are draft ready, but untested.

This phase (first half of 2021):

Next we are inviting tech writers to adopt and create a template from our prioritized wish-list of templates to write. We will be testing our base template by using it - and we will collect feedback into the base template.

Adopting a template is a reasonable commitment, but is achievable for one person to tackle. It involves:

• Learning the base template.
• Researching and documenting best practices in use for your doctype.
  • This typically involves researching business processes and communication theory.
• Collaboratively refine the template with others.

We’ll move through stages of:

• Nothing -> Something -> Better -> Best

At the end of this push, we expect to have a more consistent, core set of templates, along with a bunch of lessons to roll into future phases.

Future:

In future:

• We’ll refine our templates drawing upon the lessons we’ve learned.
• We’ll expand the range of templates we cover.

Open Source Documentation Panel - Contributing.today

 

I joined a panel at Contributing Today talking about open source documentation with:

• Scott Riley, product designer Gitbook, author of Mindful Design
• Lorna Mitchell, developer advocate Aiven, maintainer rst2pdf
• Jen Weber, web developer and writer at Ember.js

Some of the topics we covered:

• What are good docs and exemplars?
• Should different specializations be used for different doc types?
• Where to start learning about being a tech writer?
• How to improve docs for your project?
• Making your open source project attractive for tech writers to join.
• Accessibility.
• Doc strategy, information architecture, processes.
• Gitbook, The Good Docs Project, Season of Docs, rst2pdf.

Tweak Google's mission?

Google has an awesome mission statement:

"To organize the world's information and make it universally accessible and useful."

Its hard not to feel inspired by this. What a valuable gift to the world! But I think it could be even better. Because this mission statement only kicks in after ideas have been written down, as “information”.

• What if we could help capture all good ideas?
• What if we could help everyone to explain their best ideas clearly and concisely, in a form that can be easily shared and understood?

This is the mission of The Good Docs Project: 

"Create best practice templates and process for open source software."

If combined, Google’s mission could become even better:

"Organize all the world's information ideas and make them universally accessible and useful." 

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.