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.

Walk your bike into the car park!

TS;DR (Too Sarky; Don't Read)

I've been riding to work for around 30 years, and every year or two you see an email such as this, and it makes me laugh every time.

Dear cyclists,

For your health and safety, please ensure that you always dismount and walk your bicycle to the car park's bike cage.

Thank you and stay safe,

Office facilities.

So here is my response:

Dear facilities,

On my ride to work I encounter:

• Squeeze points on main roads shared with cyclist killing machines,
• Stressed and agro peak hour traffic,
• Super slippery road plate,
• Unmaintained and destabilizing bike paths,
• I could go on ...

And in the last 50 metres of my ride, travelling at walking speed into a quiet car park, where the worst that could happen is I might slip on polished concrete and bruise a hip; at that point my employer becomes concerned about my safety and encourages me to walk my bike?

(This is not a complaint, or an ask for action. Just an opportunity to share in the humour of the situation.)

One of your friendly cyclists.

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." 

Cycle Manly to Frenchs Forest

Here is a beautiful ride from Manly to Frenchs Forest using only quiet backstreets, cycle paths, tracks and fire-trails.

Cycle Manly to Frenchs Forest.

Enjoy the journey!