@bobcatwilson

Write Better DocsMoar inclusivity!

Moar quality!Open Source Summit 2018

@bobcatwilson

Hi!I’m Christie Wilson!Engineer @ Google

Container Tools Team

@bobcatwilson

The Open Source Dream

@bobcatwilson

Github 2017 stats

@bobcatwilson

The Open Source Dream

@bobcatwilson

The Open Source Dream

@bobcatwilson

Docs for Developers

@bobcatwilson

@bobcatwilson

1. Issues2. CONTRIBUTING.md

+ DEVELOPMENT.md

3. A surprise!

@bobcatwilson

Issues

@bobcatwilson

Contributing: finding an issue

@bobcatwilson

?

@bobcatwilson

:(

@bobcatwilson

Example of a good issue

github.com/knative/serving/issues/1859

@bobcatwilson

@bobcatwilson

Talking with maintainers

@bobcatwilson

The 3 keys to great issues!

● Observed behaviour○ Links to the relevant code○ Snippets

● Expected behaviour● Steps to repro

○ Environment○ Commands

Screenshots, images, links

@bobcatwilson

Github features● Use an issue template

@bobcatwilson

Github features● Use labels!

○ good-first-issue○ help-wanted

@bobcatwilson

How does Jaz get started on the issue?● Needs to know how to run tests● Your lib also runs as a service, needs to be

able to run it● Needs to know how the pull request workflow

works

@bobcatwilson

@bobcatwilson

1. Issues2. CONTRIBUTING.md +

DEVELOPMENT.md3. A surprise!

@bobcatwilson

CONTRIBUTING.mdand

DEVELOPMENT.md

@bobcatwilson

@bobcatwilson

CONTRIBUTING.md DEVELOPMENT.md

Standard recognized by GitHub (e.g., integrated into PRs)

Extends CONTRIBUTING.md

(less standard)

@bobcatwilson

CONTRIBUTING.md DEVELOPMENT.md

HOW to contribute to your repo.

Examples:- PR process- Issue requirements- Commit message style

WHAT a maintainer/contributor does.

Examples:- Build steps- Running tests- Debugging tips

@bobcatwilson

@bobcatwilson

@bobcatwilson

@bobcatwilson

How to write a great CONTRIBUTING.md● Be friendly :D● This is the welcome mat to your repo!● A greeting to potential new contributors!● The beginning of a new relationship

@bobcatwilson

How to write a great CONTRIBUTING.md● How to open an issue● How to suggest features● What contributions you’re looking for● Project philosophy● Project roadmaps● Slack/group chat/mailing lists

@bobcatwilson

If all projects were the same….● Who here uses Go?

@bobcatwilson

If all projects were the same….● Who here uses Go?● Who builds and tests ONLY with:

○ go test○ go build

@bobcatwilson

If all projects were the same….● Who here uses Go?● Who builds and tests ONLY with:

○ go test○ go build

● i.e. you never have to use Makefiles, or scripts, etc.

@bobcatwilson

Unless all projects are identical,If you want contributors,

you need to explain how your project works!

@bobcatwilson

Get the process out of your brainand into markdown!

@bobcatwilson

How to write a great DEVELOPMENT.md● The less you assume, the more people can contribute!● Even super experienced folks:

○ Are new to your project○ May use different tools○ Have had different experiences

@bobcatwilson

Even experienced devs use different toolsJaz uses:

● Github● Go● Kubernetes

Andy uses:

● Java● SVN● In-house bare metal

Wendy uses:

● C#● Visual Studio● Azure

@bobcatwilson

How to write a great DEVELOPMENT.md● How to fork● How to setup an environment for development

○ Tool and resource requirements○ Interacting with the system

● How to iterate○ How do you check something works? e.g. tests, poking manually○ e.g. keeping vendor/ up to date, redeploying, cleaning up

@bobcatwilson

Example DEVELOPMENT.md

The knative/serving DEVELOPMENT.md

knative/serving DEVELOPMENT.md

@bobcatwilson

1. Issues2. CONTRIBUTING.md

+ DEVELOPMENT.md

3. A surprise!

@bobcatwilson

Jaz found a bug in your lib!

@bobcatwilson

Jaz found a bug in your lib!

@bobcatwilson

Why 5?

@bobcatwilson

Why 5?

@bobcatwilson

1. Issues2. CONTRIBUTING.md

+ DEVELOPMENT.md

3. Commit messages

@bobcatwilson

Commit Messages

Thanks Steven Erenst for teaching me about the value of commit messages!

@bobcatwilson

@bobcatwilson

Commits often look like this:

“Fix missing logs”

“Fixes #22 and #5”

“Bump the timeout to 20 min”

@bobcatwilson

@bobcatwilson

Example good commit messageSubject Line

Background

Description

@bobcatwilson

y tho

“logrus use full timestamp”

@bobcatwilson

y tho

“Change default action to ‘inplace’”

@bobcatwilson

y tho

“Change git commit to use short ID instead”

@bobcatwilson

Context switching

@bobcatwilson

Context switching

Commit

@bobcatwilson

Context switching

Commit Pull Request

@bobcatwilson

Context switching

Commit Pull Request Issue

@bobcatwilson

Context switching

Commit Pull Request Issue Human

@bobcatwilson

Context switching

Commit Pull Request Issue Human

Bug

Commit Pull Request

CommitCommit

Pull RequestPull Request

Commit

@bobcatwilson

Example good commit messageSubject Line

Background

Description

@bobcatwilson

How to write great commit messages● Subject line (what does this commit do?)● Body that explains what and why vs. how● Two paragraphs

@bobcatwilson

What + Why v.s. HowHow do you fill 2 paragraphs?

● What is the problem being solved?● Why is this the best approach?● What other approaches were considered?● What side effects will this approach have?● What future work remains to be done?

Thanks Thomas Stromberg!

@bobcatwilson

Great docs are a prereqfor a strong contributor base!

@bobcatwilson

Great docs for a better world!● Remote first!● Different lifestyles!● People all over the globe!● Welcome different kinds of contributors!

@bobcatwilson

How?

1. Dogfood your own internal docs

2. Complete PR = Code + Tests + Docs

Make docs part of your process!

@bobcatwilson

@bobcatwilson

Thanks!

@bobcatwilson

Links!CONTRIBUTING.md:https://help.github.com/articles/setting-guidelines-for-repository-contributors/

https://opensource.guide/starting-a-project/#writing-your-contributing-guidelines

https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md

Community building:https://help.github.com/categories/building-a-strong-community/

https://opensource.guide/starting-a-project/

https://medium.freecodecamp.org/how-to-attract-new-contributors-to-your-open-source-project-46f8b791d787

GitHub and issues:

https://help.github.com/articles/using-templates-to-encourage-high-quality-issues-and-pull-requests-in-your-rep

ository/

https://github.com/codeforamerica/howto/blob/master/Good-GitHub-Issues.md#writing-good-github-issues

https://help.github.com/articles/helping-new-contributors-find-your-project-with-labels/

Commit messages:

Implementing a Strong Code Review Culture

https://chris.beams.io/posts/git-commit/