Early stage documentation: From chaos to clarity!
A presentation at WriteTech Hub Bootcamp by Ruth Cheesley
Early stage documentation: From chaos to clarity! WriteTech Hub Bootcamp 5th June 2025 @RCheesley
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
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
It’s time to wake up, folks! There’s going to be audience participation and breakout groups, so it’s time to pay attention!
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
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
Why focus on early-stage projects?
The docs landscape in early-stage projects
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
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
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
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
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
Are they already asking for help?
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
Finding ways to contribute
Content CLEAR? A suggestion for how to review and assess a project’s documentation quality https://bit.ly/clear-framework Layout Examples Audience Recency
Content CLEAR? A good place to start is with the actual content written in whatever documentation a project has available. Layout Examples Audience Recency
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?
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
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.
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
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?
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
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?
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
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?
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!
Join us on Canva! https://www.canva.com/design/DAGouh3RWi4/ CYDrvi6Dls1g2kV73LTWfg/edit
Welcome back! fi Hope you had fun reviewing some open source projects and nding areas for improvement!
Making an impact as a technical writer How you can help maintainers better serve their users as a technical writer
Content CLEAR? How can you make an impact by improving content for an open source project? Layout Examples Audience Recency
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
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
• 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.
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
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
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
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
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
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
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!
Let’s go back to Canva! https://www.canva.com/design/DAGouh3RWi4/ CYDrvi6Dls1g2kV73LTWfg/edit
Making that rst outreach fi How to reach out and offer to help maintainers of open source projects you’re new to
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!
• 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:
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
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
Everyone still with us? Let’s agree on your take-home tasks
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.
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
Resources
The following resources were mentioned during the presentation or are useful additional information.
