Documentation for Developers

Slide 1

Slide 1 text

Documentation for Developers Katherine White  WordCamp US 2017

Slide 2

Slide 2 text

What we’ll cover • Why write docs • What technology • What to write

Slide 3

Slide 3 text

Why Write Docs

Slide 4

Slide 4 text

Why Write Docs • You (or someone else) will be using your code in six months • You want people to use your code … or to even help out • It makes your code stronger • It builds community • It makes you a better writer

Slide 5

Slide 5 text

What Technology

Slide 6

Slide 6 text

What Technology • Simple is best • Use plain text • Keep it with the code • If it’s version controlled, it’s canonical

Slide 7

Slide 7 text

Markdown

Slide 8

Slide 8 text

Markdown • Widely supported by version control (GitHub, GitLab, BitBucket) • Automagically formats for display • Plain text format • markdowntutorial.com

Slide 9

Slide 9 text

README.md Public repository example: http://bit.ly/2zcfgkx Private repository example: http://bit.ly/2hadc8h

Slide 10

Slide 10 text

CONTRIBUTING.md Creation guide: http://bit.ly/2zhQ5iC

Slide 11

Slide 11 text

What to write

Slide 12

Slide 12 text

What to Write • What problem does it solve? • What are the major features? • How do you install it? • Code examples and tutorials • How to reach a human for help • Links to code and issues • Changelog • Licensing information -  https://choosealicense.com/

Slide 13

Slide 13 text

What to Write • Public and private repos need diﬀerent care and feeding • Consider your audience • Keep it up to date • If you’re inviting contributions, tell people what to expect

Slide 14

Slide 14 text

Conclusion • Why write docs • What technology • What to write

Slide 15

Slide 15 text

Questions & Feedback • Here and now • [email protected] • @katherinemwhite