Early stage documentation:
From chaos to clarity!

A presentation at WriteTech Hub Bootcamp in June 2025 in by Ruth Cheesley

Slide 1

Slide 1

Early stage documentation: From chaos to clarity! WriteTech Hub Bootcamp 5th June 2025 @RCheesley

Slide 2

Slide 2

Ruth Cheesley (she/her) Mautic Project Lead & Co-Founder, Women of Open Source community ruth.cheesley@mau c.org speaking.ruthcheesley.co.uk for slides, recording, links and resources ti @RCheesley

Slide 3

Slide 3

Documentation landscape in early-stage open source projects: what to expect, common patterns and the problems maintainers face. What we’re covering. 2. By ‘early-stage’ I mean any project that doesn’t already have a strongly de ned documentation team responsible for maintaining and improving their documentation. Making an impact as a technical writer in an early-stage open source project: how you can make high-impact contributions. 3. Interactive hands-on breakouts: reviewing the documentation for early-stage projects, prioritising improvements, and making that rst contribution. fi fi @RCheesley

Slide 4

Slide 4

It’s time to wake up, folks! There’s going to be audience participation and breakout groups, so it’s time to pay attention!

Slide 5

Slide 5

2003 2008 2012 Started using open source tools (Knoppix, Needing to pay off loans from Started working with Joomla as my main Ubuntu, ClamAV, HijackThis) to fix infected University, I started building occupation, proposed my first talk for the computers for other students while at Uni, Joomla! websites and freelancing Joomla World Conference in San Jose - as ‘Essex Virus Removals’. alongside work. created GitHub account! My contribution journey Section divider 2007 2009 My first job in IT after graduating as a Started a local Joomla user group as I physio! Working in a school as an IT wanted to meet other Joomla users and Technician, I was asked to rebuild the find ways to do things / have people to website. Came across Content ask when I got stuck. We met monthly Management Systems (Drupal, Joomla!) and quickly gained a committed group of and started using Joomla. members. @RCheesley

Slide 6

Slide 6

2013 2015 2020 Created my first bug report on Raised my first issue and PR for Stepped up to Mautic Project Lead. GitHub! Invited to join the Joomla Mautic - a project that has just Led my first release, established our Community Leadership Team to launched and which I used for community governance model, support User Groups and Marketing. clients in our Digital Agency. teams and values. Section divider 2014 2019 Created my first PR at a Pizza, Bugs Started work at Acquia as Mautic and Fun event to fix a bug in Joomla, Community Manager, helping the which was merged the day after it was open source community to establish submitted! 🥳 its own governance and autonomy from the corporate entity which was Joined the Joomla Marketing Team. acquired by Acquia in 2019. @RCheesley

Slide 7

Slide 7

Why focus on early-stage projects?

Slide 8

Slide 8

The docs landscape in early-stage projects

Slide 9

Slide 9

The jargon-heavy introduction. • Documentation is packed with unexplained technical acronyms • Assumes expert knowledge of the area, without linking to beginners tutorials for assumed knowledge • No clear explanation of the project’s purpose, what it does, how it does it and why it’s used • Limited ‘quick start’ guidance or getting started steps

Slide 10

Slide 10

The README-or-else project! • All the documentation exists in a single README le • Usually very technical • Often assumes knowledge of technology used • Additional information and new changes is scattered across PRs, issues and chat conversations • Substantial ‘technical docs debt’ due to lack of fi quality standards

Slide 11

Slide 11

Inadequate con guration docs. • No explanation of con guration options • Missing default values or con guration snippets • Lack of clarity for required v optional settings • Ambiguous comments (e.g. ‘add custom plugins here’ - how?) fi fi fi fi • No examples of complete con gurations

Slide 12

Slide 12

Outdated tutorials. • Refers to old versions or incorrect instructions • Outdated screenshots which don’t match the product • Referencing features which have changed or no longer exist • No indication of changelog or what has changed since it was written

Slide 13

Slide 13

Fragmented documentation. • Information scattered across multiple locations • No clear path for users to understand how to get started or contribute • Users forced to hunt for the basic information • Inconsistent formats across documentation resources • Relies on internal or pre-assumed knowledge

Slide 14

Slide 14

Are they already asking for help?

Slide 15

Slide 15

Finding existing tasks. • Check for labels like ‘documentation’ - especially if they’re combined with ‘good rst issue’ • Search discussions (chat, GitHub discussions, mailing lists etc), project management tools etc. for references to documentation being needed • Search PRs for references to needing documentation - sometimes this might be a label, sometimes a passing comment that the docs need writing or are missing/outdated. fi ti https://github.com/organiza on/repo/labels

Slide 16

Slide 16

Finding ways to contribute

Slide 17

Slide 17

Content CLEAR? A suggestion for how to review and assess a project’s documentation quality https://bit.ly/clear-framework Layout Examples Audience Recency

Slide 18

Slide 18

Content CLEAR? A good place to start is with the actual content written in whatever documentation a project has available. Layout Examples Audience Recency

Slide 19

Slide 19

Content Assessment. CLEAR? 1. Here’s some tips for where to start when reviewing the content of an open source project’s documentation resources. 2. Does the README explain what the project is, what it does, how to install/con gure/use it? Are pre-requisites or dependencies mentioned? Do the steps provided to get started actually work? Could you get it installed and con gured without any external searching? 3. fi fi Are there any links that don’t work, references to outdated code, or code samples which don’t match the currently supported version?

Slide 20

Slide 20

Content CLEAR? Layout is an important aspect when it comes to documentation of open source projects. Good content with a poor layout can make for a painful experience! Layout Examples Audience Recency

Slide 21

Slide 21

Layout and structure assessment. Here’s some areas relating to layout and structure where we commonly see open source projects struggling, or not optimising the experience for their users. 2. Could you easily nd the documentation, or is it fragmented across multiple locations or not linked clearly from the README? Is it logically laid out, with clear sections and linked headings? Do longer documents have a table of contents? Are all the links working, and going to the right anchors? Does the structure make sense? 3. Does the navigation make sense? Can you easily nd what you’re looking for? Are there links between sections, where relevant (e.g. if mentioning a different feature) fi fi CLEAR? 1.

Slide 22

Slide 22

Content CLEAR? Examples can be critical for new users, whether it’s speci c con gurations to be copy/pasted or use cases for how the product is used, it all helps with onboarding. Layout Examples Audience fi fi Recency

Slide 23

Slide 23

Examples and explanations. CLEAR? 1. Here’s some areas where you can review the examples and explanations that are used by an open source project. 2. Is technical language explained or avoided? Could you understand everything that was written, as a newcomer to the project? Are there suf cient examples for key features and functions? Do the examples take you from a new user through to a more seasoned, experienced user? 3. fi fi fi Are there examples and explanations which cover different use cases, helping people to understand where this project ts their speci c needs?

Slide 24

Slide 24

Content CLEAR? Open source projects often have to cater to several audiences - developers, users, implementors and more. It’s an important dimension to consider when reviewing documentation. Layout Examples Audience Recency

Slide 25

Slide 25

Audience adaptation. CLEAR? 1. Here’s some areas where open source projects often don’t optimise their documentation for speci c audiences. 2. Is there helpful documentation for people at every stage of their journey with the project, from beginners to experts? Are advanced / specialised topics separated from the basics to avoid confusing newcomers? Is it easy to nd speci c advanced technical information? 3. fi fi fi Are there any assumptions made about pre-required knowledge? Is there a clear getting started guide, both for using the project and also for contributing and setting up a local environment?

Slide 26

Slide 26

Content CLEAR? Keeping documentation up to date is a never-ending task for open source projects, and many fall behind quite easily. Layout Examples Audience Recency

Slide 27

Slide 27

Recency and relevance. CLEAR? 1. A suggestion for how to review and assess a project’s documentation quality 2. Are there code samples and screenshots which don’t represent the current state - for example outdated code or screenshots which don’t match the current experience? Have the documentation resources been reviewed and updated to ensure that they’re culturally appropriate, written without bias and using inclusive language? 3. Have new features introduced in recent releases been added to the documentation with clear information about what they do, how to use them, and how to troubleshoot?

Slide 28

Slide 28

Time to wake up! Let’s take a look at some open source project readme’s and identify some documentation gaps or issues that could be xed. fi fi Other teams will use your ndings in later breakouts!

Slide 29

Slide 29

Join us on Canva! https://www.canva.com/design/DAGouh3RWi4/ CYDrvi6Dls1g2kV73LTWfg/edit

Slide 30

Slide 30

Welcome back! fi Hope you had fun reviewing some open source projects and nding areas for improvement!

Slide 31

Slide 31

Making an impact as a technical writer How you can help maintainers better serve their users as a technical writer

Slide 32

Slide 32

Content CLEAR? How can you make an impact by improving content for an open source project? Layout Examples Audience Recency

Slide 33

Slide 33

Making an impact: Content. • Write a clear, user-friendly project overview ‘what is this’, ‘who is this for’, etc • Create a quick-start guide/tutorial • Fix any broken, incorrect or outdated content you come across • Suggest or create a documentation style guide (where appropriate - larger projects) • Implement a linter to ag content issues and fl improve the quality and consistency of docs

Slide 34

Slide 34

Content CLEAR? What can you help to improve when it comes to the layout of an open source project’s documentation? Layout Examples Audience Recency

Slide 35

Slide 35

• Consider whether a separate documentation system (e.g. Read the Docs or similar) would be bene cial, especially with larger/more complex projects with different versions • Improve the experience with table of contents, organising using sections with headings, and centralising scattered documentation • Add internal and external links to help people nd relevant information, know where to go next, etc. fi fi Making an impact: Layout.

Slide 36

Slide 36

Content CLEAR? Examples and explanations are critical in helping new users to understand and adopt open source tools, how can you make an impact? Layout Examples Audience Recency

Slide 37

Slide 37

Making an impact: Examples. • Add beginner-friendly examples and step-bystep walkthroughs including copy-paste code samples to help newcomers • Expand example coverage to ensure all features, con guration options and settings are documented • Clarify technical language, especially if it’s fi fi something speci c to this kind of technology or project

Slide 38

Slide 38

Content CLEAR? Open source projects often have to cater to several audiences - developers, users, implementors and more. It’s an important dimension to consider when reviewing documentation. Layout Examples Audience Recency

Slide 39

Slide 39

Making an impact: Audience. • Separate beginner, intermediate and expert content into different sections • Add or improve contributor guides to help new users set up their local environment, nd tasks to work on, understand coding standards and tooling used, and creating PRs • List prerequisites and clearly state assumed knowledge, linking to where to learn more • Create FAQs for common questions of different fi experience levels

Slide 40

Slide 40

Content CLEAR? How can you have an impact by helping an open source project with keeping its documentation up to date? Layout Examples Audience Recency

Slide 41

Slide 41

Making an impact: Recency. • Check recent releases and ensure that all new features are fully documented - if not, offer to write the docs • Refresh code samples, screenshots and instructions to match the current version • Add a documentation changelog so users can tell when resources were last updated • Review the docs for inclusivity, tone and accessibility against current industry and cultural expectations

Slide 42

Slide 42

Time to wake up! Using the notes that were taken in the rst round of breakouts, we’re now going to consider what we could contribute. fi Join a different breakout room to the one you started in!

Slide 43

Slide 43

Let’s go back to Canva! https://www.canva.com/design/DAGouh3RWi4/ CYDrvi6Dls1g2kV73LTWfg/edit

Slide 44

Slide 44

Making that rst outreach fi How to reach out and offer to help maintainers of open source projects you’re new to

Slide 45

Slide 45

Making the rst contribution: • Don’t lead with how awful their documenta on is or a laundry list of the things you’ve found wrong - none of us like having our faults pointed out to us! • Introduce yourself, tell them why you want to help them with this project, and outline what you’ve found and xed in your rst contribution • Start out with small, well scoped tasks which are quick to review and merge - wait for the rst to be merged before submitting more ti fi fi fi fi • Listen to feedback and reply promptly!

Slide 46

Slide 46

• Always use the PR template and ensure you include all relevant details • Highlight if you’re xing an open issue or building on an existing / earlier PR • Call out speci c changes which the maintainer should be aware of • Use the right branch as your base • Keep your PRs small, concise and focused. Don’t fi ood maintainers with lots at once or huge PRs fi fl What makes a PR easy to accept:

Slide 47

Slide 47

How to propose larger changes: • Talk with maintainers before starting • Explain what you’re proposing, why, and how it will help the project • Call out directly the impact it will have and how it will improve things • Be willing to listen to feedback • Ensure that it’s maintainable without you being around going forward - link to docs and resources to help the maintainers future-proof your contributions

Slide 48

Slide 48

Respecting maintainers: • Don’t ghost them - if you’re only able to contribute for a few months (e.g. as part of a project or a course) be clear about that upfront • Check that your prioritisation aligns with their vision for improvement - don’t assume you know what’s most important • Do your own homework - don’t expect them to teach you about the tool unless you’ve already made efforts to learn for yourself • Use AI responsibly, if at all, and always declare when you’ve used it and why

Slide 49

Slide 49

Everyone still with us? Let’s agree on your take-home tasks

Slide 50

Slide 50

Tasks for this week. Make your rst steps toward contributing to a project you’ve encountered today or one you already know about 3. Review the Canva board, and if something takes your interest from the second round of contribution ideas, write your name on the sticky note and make that contribution Apply the CLEAR framework with an open source project that you know of and want to help, see what you nd, and begin the process of contributing to the project Have a conversation with a maintainer of a project that you’re interested in. If you would like an introduction to any of the projects listed in the Canva board, ping me fi 2. fi 1.

Slide 51

Slide 51

Ruth Cheesley (she/her) What questions can I answer? ruth.cheesley@mau c.org speaking.ruthcheesley.co.uk for slides, recording, links and resources ti @RCheesley