Electrifying friends

It’s surprising to discover the knock-on impact each of us has when we become that trusted friend who helps people or communities with their electrification journey.

This Electrifying Friends presentation covers:

• Why electrifying homes is a major solution to our climate challenges.
• Why trusted friends are a key enabler.
• Why lessons us Australians work will be rolled out to the world.
• How to become a good electrification champion.

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.

Time to retire Contributor License Agreements

Imposing Contributor License Agreements (CLAs) on open source contributors inadvertently imposes unnecessary legal risk on the people gifting software to humankind. It’s time to:

• Update the legal advice from foundations,
• Update license terms of hosting platforms,
• And help open source communities avoid wasting energy on CLAs.

Reading time: 6 mins

What are CLAs?

Contributor License Agreements (CLAs) are “inbound licenses” - providing a license from a contributor into a project. This contrasts to “outbound” open source licenses such as the GPL or Apache licenses, which provide a license from a project to users. There are multiple individually crafted CLAs (which is a problem in itself), which typically consist of a combination of:

• Individual Contributor License Agreements (ICLA): An individual asserts that they license their contributions to the project, and they have the right to do so.
• Corporate Contributor License Agreements (CCLA): A corporation asserts their employees may contribute to the project.
• Copyright Assignments (CA): Contributors assign copyright to the project’s owners (typically a not-for-profit organization).

What are the arguments for CLAs?

Proponents for CLAs often argue that CLAs add licensing rigor and help protect a project and its end users from being sued by bad actors. For instance, the Ubuntu/Canonical FAQ notes:

Q: Why do you ask contributors to send in the [contributor license] agreement?

A: We need to make sure that we ‐ and the users of our software ‐ are legally entitled to distribute your contributed code, anywhere in the world.

Why the Free Software Foundation gets copyright assignments from contributors:

In order to make sure that all of our copyrights can meet the recordkeeping and other requirements of registration, and in order to be able to enforce the GPL most effectively, FSF requires that each author of code incorporated in FSF projects provide a copyright assignment, and, where appropriate, a disclaimer of any work-for-hire ownership claims by the programmer's employer. That way we can be sure that all the code in FSF projects is free code, whose freedom we can most effectively protect, and therefore on which other developers can completely rely.

What’s wrong with CLAs?

The problem with Contributor License Agreements (CLAs) are that they:

• Are at best legal voodoo. In the current unformed state of intellectual property law, CLAs don’t provide a water-tight defense against the legal attack they are theoretically supposed to prevent.
• Are arguably unnecessary, now that “inbound=outboud license terms” have started being woven into some hosting platform Terms of Service.
• Shift legal risk to contributors.
  • CLAs shift the legal risk for copyright infringement, patent infringement or other bad acts,
    • From the project and end users (the entities best positioned to defend a legal claim, and often the ones most directly benefiting financially),
    • To the contributor (the one in at the least advantaged negotiation position, often volunteering their time for the project’s benefit).
• Rely on our Don't Read & Click ‘Agree’ culture — tricking contributors into bearing legal risk.
• Create a contribution-hostile environment. CLAs require that the first interaction between an open source project and a potential contributor involves a formal and complex legal agreement which signs away their legal rights — not exactly a warm welcome.
• Require significant administrative overhead. The project needs to stand up a system to track every potential contributor that has signed the agreement.

Alternative 1: Do nothing

If your project has selected an open source license, and you are using a platform like Github, which includes an “inbound=outbound” clause in its terms of service, then your project is likely covered to the same extent as you get from a CLA.

Alternative 2: Simple statement

You can add a simple statement to your project’s contributor guidelines. Erik S. Raymond suggests:

By submitting patches to this project you agree to allow them to be redistributed under the project's license, according to the normal forms and usages of the open-source community.

Alternative 3: Developer Certificate of Origin

You can reference the Developer Certificate of Origin (DCO) in your project’s contributor guidelines:

By contributing to this project we expect you to agree to the Developer Certificate of Origin (DCO).

The (DCO) provides a simpler alternative to CLAs. It is a simple statement that a contributor agrees to share their contribution under the project’s license terms, and has the rights to do so. It’s advantages are:

• It is short, simple and easy to understand.
• It can be referenced by any project without customisation.
• It can be set up without engaging a lawyer.
• It is used by trusted open source foundations, giving it credibility within open source communities.
• It has negligible project management overhead. Tracking of agreements is managed by the code versioning system.
• It doesn’t introduce a copyright assignment, which is a barrier for some contributors.

Possible disadvantages are:

• Like CLAs, DCOs don’t provide a water-tight defense against the legal attack.
• It could be argued that a simpler statement of “inbound licenses = outbound licenses” provides the same purpose as the DCO, but does so more elegantly.
• While the DCO can be applied without explicit signatures for each commit, some projects, such as the Linux Foundation, require each commit to be electronically signed. The electronic signature adds a technical overhead which can deter some contributors.
• Some entities (such as not-for-profit organizations) might be concerned that copyright is not assigned to their entity.

What should projects do?

Adopt one of the three alternatives above.

What should open source foundations do?

Open source foundations have earned a position of trust, respect and influence within software communities.

It is important for these foundations to:

1. Research and understand the problems associated with CLAs.
2. Revisit and ideally migrate off CLAs for projects within their foundation.
3. Collaborate and adopt common language around the replacement to CLAs.
4. Provide prominent advice to communities against the use of CLAs.

What should software hosting platforms do?

Software hosting platforms should follow the lead of Github and legally protect the projects they host. Add “inbound=outbound” to their license terms of service.

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