Effective Documentation: The Key to Open Source Growth

Effective Documentation: The Key to Open Source Growth

Bolaji Ayodeji

Developer Advocate at Commerce Layer

Talk Contents

```
Introduction to OS Documentation
```
```
The Myths of Open Source
```
```
Understanding User Personas
```
```
The Effective Docs Strategies
```
```
Bad Documentation Checklist
```
```
Good Documentation Checklist
```
```
Useful Documentation Tools
```
```
What Next?
```

Introduction to OSS Documentation

In open source, documentation is the information that describes a project to its users and contributors.

The Myths of
Open Source

Open source is the responsibility of the creator alone

```
Open source is just about code
```

Open source software is less secure than proprietary software

Understanding User Personas

```
👥 End Users
```
```
👨🏾‍💻 Developers
```
```
👩‍🎨 Designers
```
```
✍🏾 Technical Writers
```
```
🧑🏼‍💼 Program Managers
```
```
💰 Financial Contributors
```

What do they want?

What do they want to get out of your project?

What solutions(s) does your project offer?

What could be their initial visit mindset?

Where are they coming from?

```
Search engine
```
```
Social media
```
```
Backlinks
```
```
Package managers
```

How much time will they dedicate?

```
What do they want?
```
```
How fast do they want it?
```
```
How fast can your Docs serve them?
```

How fast can you respond to their issue(s)?

```
How satisfied will they be?
```

How technical savvy are they (Users && Contributors)?

```
Newbie
```
```
Beginner
```
```
Junior
```
```
Intermediate
```
```
Expert
```
```
Distinguished
```

The Effective Docs Strategies

Define a documentation vision for your project

What are the core reasons for people engaging with your project?

Define your target state

Be clear and realistic about your documentation goals.

Do a gap analysis between the current and target state

Analyze your current documentation state and target state. Ensure to document the differences.

Introduce approaches and/or processes to reach the target state

Set up and execute your documentation processes

Start small and prioritize sustainability.

Sustainability

Make sure you have sufficient plan, team, or community to maintain your documentation.

Quality over quantity

Leverage other techniques aside “text-related content”

```
Visual Documentation
```
```
Use Cases
```
```
Working Samples
```
```
Testimonials
```
```
Metrics
```

Build a community around your documentation

Attract collaborators, sell the vision, recruit help and simplify the contribution process.

Automate and track revision history

Bad Documentation Checklist

❎

```
Doesn’t scale with your project
```
```
Repeats patterns
```
```
Ambiguous
```
```
Not inclusive
```
```
Missing contributors guide
```
```
Doesn’t include support link(s)
```

Good Documentation Checklist

✅

```
Why was this project created?
```
```
What problem(s) does it solve?
```
```
How can I get started with it?
```
```
Where has this project been used?
```
```
Who is using it?
```
```
Some live use cases
```
```
How can I contribute?
```
```
Where can I get help?
```

Useful Documentation Tools

All Contributors Bot (Recognize all contributors including those that don't push code).

The Good Docs Project (Best practice templates and writing instructions for documenting open-source software).

Google Season of Docs (Support for open source projects to improve their documentation).

Awesome technical writing (A curated list of awesome resources about technical writing).

Awesome docs (A curated list of awesome documentation tools).

What next?

Define a documentation vision for your project and prepare goals.

Build a community around your documentation and ensure you prioritize sustainability at the early stages of your project.

Your documentation should provide users with a roadmap to using your project

Documentation helps your users succeed with your software, empowers them to be self-sufficient, enables them to give further feedback, and is the organizational backbone of your project.

Thank you!

Bolaji Ayodeji

Developer Advocate at Commerce Layer

🐦 @iambolajiayo

🌐 www.bolajiayodeji.com