WPCampus: Documentation for Developers

Slide 1

Slide 1 text

Documentation for Developers Katherine White WPCampus 2018

Slide 2

Slide 2 text

What we’ll discuss 01 02 03 Why it matters Audiences What to include 04 05 06 Keeping it fresh Making it happen Writing your docs

Slide 3

Slide 3 text

01 Why it matters The role documentation plays for your projects and for you.

Slide 4

Slide 4 text

You will be using your code  in a year. Code you wrote six months ago looks like it was crafted by a mad genius. MAINTAINABILITY

Slide 5

Slide 5 text

Someone else will be using your code in a year. Almost 35% of developers cite poor documentation as one of their primary frustrations at work, just behind “unrealistic expectations.” - Stack Overﬂow Developer Survey, 2016 MAINTAINABILITY

Slide 6

Slide 6 text

You want people to use your solution. Consistency is always a challenge. People don’t use things that aren’t easy to ﬁgure out. ADOPTION

Slide 7

Slide 7 text

You want to build a community. To encourage participation, people must grasp the value of the project and how they contribute to it. ADOPTION

Slide 8

Slide 8 text

You want to write stronger, better code. If you want to be sure you understand it, explain it to someone else. PERSONAL GROWTH

Slide 9

Slide 9 text

You want to improve your marketability. Practice makes perfect. The more you write, the easier it becomes. PERSONAL GROWTH

Slide 10

Slide 10 text

02 Audiences The people who inﬂuence your documentation.

Slide 11

Slide 11 text

Stakeholders • May or may not be technical • Understand the business requirements • Care about the organizational impact • Help pay the bills • Drive adoption (or death) of your project

Slide 12

Slide 12 text

Implementers • Have a problem they need to solve • Varying degrees of technical facility • Strapped for time and resources • Need to interact with your functionality but not your code • Can be inside or outside your institution

Slide 13

Slide 13 text

Developers • Adapt and extend your code • Interested in being part of your open source project • Technical teammates • Support the work long-term

Slide 14

Slide 14 text

03 What to include Writing clear plugin documentation and beyond.

Slide 15

Slide 15 text

For Everyone ✓ What problem are you solving? ✓ How does the thing work? ✓ What are the major features? ✓ How do you install it? ✓ What is it built with? ✓ Where can you get help? ✓ When can you use it? ✓ What has changed between versions?

Slide 16

Slide 16 text

For Developers ✓ How do you set up a local? ✓ How is your project architected? ✓ What are rules of the road? ✓ How is it tested? ✓ How is it deployed?

Slide 17

Slide 17 text

04 Writing your docs This doesn’t have to be hard. Promise.

Slide 18

Slide 18 text

Your writing matters. • Avoid overly technical jargon • Add links to supporting documentation • Add links to acronyms, technical terms, and third party tools STYLE

Slide 19

Slide 19 text

Think in stories. User stories are a powerful tool for simplifying the explanation of what your code does and why. STYLE As a [user from the user group], I should [description] so that [user-centric reason/strategic benefit/business justification.]

Slide 20

Slide 20 text

Be consistent. Update your documentation regularly as you plan and build your project. It keeps you in the habit and means you don’t have to go back and do it later. STYLE

Slide 21

Slide 21 text

Don’t scope creep. Nobody likes lengthy spec documents. Break your documentation up so it lives at the deepest possible level. STYLE

Slide 22

Slide 22 text

Do what you know. Use a simple text-based format that’s lightweight and ﬂexible. Don’t make this hard. Do what you know. Markdown is pervasive and easy to learn. STRUCTURE

Slide 23

Slide 23 text

Start with a README. A basic overview of your project, theme, or plugin. If you have nothing else, have this. STRUCTURE

Slide 24

Slide 24 text

Have a LICENSE. Provide a LICENSE ﬁle that clearly delineates how your code can be used. For WordPress, it should be compatible with GPL v2 or higher. https://choosealicense.com/ STRUCTURE

Slide 25

Slide 25 text

Help others CONTRIBUTE. A CONTRIBUTE ﬁle provides a home for information on patching, code review practices, and any other development speciﬁc criteria. STRUCTURE

Slide 26

Slide 26 text

Writing Resources • Grammarly: Free Writing Assistant • Readable.io • Hemmingway Editor  • Markdown Tutorial • Markdown Cheatsheet • StackEdit

Slide 27

Slide 27 text

05 Keeping it fresh Staying accurate and accessible in your documentation.

Slide 28

Slide 28 text

Have a canonical source. Decentralized documentation hurts. Don’t rely on scattered project artifacts or granular commit messages.

Slide 29

Slide 29 text

Track changes over time. Keeping documentation in your version control system gives a clear picture as code and requirements evolve.

Slide 30

Slide 30 text

Keep it with the code. The code is the only “artifact" that will exist for the full life of your project.

Slide 31

Slide 31 text

Leverage pull requests. Key moments in the code history can provide more granular documentation. Use a template to add structure.

Slide 32

Slide 32 text

Leverage release notes. Change logs don’t just help your users. They help you a year from now.

Slide 33

Slide 33 text

Include project docs. You can use this model, with a   /docs/ folder, to support full project documentation that will always live with your site.

Slide 34

Slide 34 text

Generate a static site. Tools like MkDocs and Couscous create HTML documentation sites that get around the limitations of just Markdown.

Slide 35

Slide 35 text

Host the HTML version. Web hosts like Read the Docs, GitHub Pages, and Netlify make it easy and free to create static documentation sites.

Slide 36

Slide 36 text

06 Making it happen Building documentation into your everyday life.

Slide 37

Slide 37 text

Make it part of the workﬂow. Consistency is key. Enforce documentation creation as part of your development process.

Slide 38

Slide 38 text

Something is better than nothing. Start small. If it is accurate, and kept up to date, it adds value.

Slide 39

Slide 39 text

The best is the enemy of the good. - Voltaire, La Bégueule ” “

Slide 40

Slide 40 text

Questions? Feedback? ? @katherinemwhite https://2018.wpcampus.org/schedule/documentation-for-developers/