Governance sounds serious. But at its core, it simply means: how do we make decisions, and who gets to make them? It doesn’t matter if you're working on a project at the grassroots level with a few maintainers or a mature open-source ecosystem – the guiding procedures influence how people contribute, manage issues, and develop into leaders.

And, like with anything in open source – if it isn't documented, it may as well not exist.

In this article, I'll explain why governance documentation is important, what to include, and how to document governing procedures that are useful, clear, and human.

Table of Contents

• Why Governance Matters (and Why You Should Document It)

• What your Governance Documentation Should Have

• Make Governing Documentation Clear and Welcoming

• How to Start Documenting Governing Procedures for Your Open Source Community

Why Governance Matters (and Why You Should Document It)

Every open-source community already has some kind of governance (even if it’s not written down). Sometimes it’s a single maintainer making all decisions. Sometimes it’s a small group of people “just knowing what’s best.” The danger here is not the structure itself but the lack of clarity around it.

When governing procedures aren’t documented:

• New contributors might be confused about how to get involved

• Decisions appear arbitrary or biased

• Power dynamics become invisible

• Conflict becomes harder to manage or resolve fairly

Documenting governance promotes trust, transparency, and predictability. It does not imply confining contributors to rigid rules – rather, it offers your community a common understanding of how things work and how they may change.

What Your Governance Documentation Should Have

You don’t need to start governance documentation from scratch. You probably already have fragments of governance in your README, CONTRIBUTING.md, or pinned messages in your community’s messaging platform. The goal is to bring them together into something clear, navigable, and contributor-friendly.

Think of your governance documentation as a map. It should help contributors understand where they are, how things work, and what paths they can take, including:

1. Mission and Values: Why does this project exist? What principles guide how decisions are made or prioritised? This can set the tone for governance and invite collaboration.

   

2. Roles and Responsibilities: Who are the maintainers? What can contributors, reviewers, and core team members do? Who can open pull requests? Review them? Approve proposals? Define expectations and boundaries clearly.

3. Decision-Making Process: How are technical decisions made? By consensus? By voting? Is there a lead maintainer with the final say? What types of decisions require community input? How are disputes resolved?

4. Conflict Resolution: What happens if people disagree? Is there a process to escalate issues respectfully?

5. Proposal Process: How are changes proposed and discussed? Do you use an RFC system, GitHub discussions, or something else? What’s the typical timeline for review or feedback?

6. Leadership Changes: How are new maintainers added? How can someone step down or be removed?

7. Amending Governance: How can the governing procedure itself and its documentation be changed? Who has the authority to do so?

8. Contributing Guidelines: How can contributors get started? How can they submit a pull request? What does review and approval look like? Is there a contributor ladder? What happens after someone contributes regularly? Make it easy for everyone to get around the overall contributor experience

   

9. Code of Conduct (linked or embedded): Governance and conduct are deeply connected. One shapes the culture, while the other protects it.

Make Governing Documentation Clear and Welcoming

Governance documentation doesn’t have to read like legal policy. In fact, it shouldn’t. A clear, welcoming tone helps readers feel included, especially newcomers or contributors from under-represented groups.

The tone you use in your governance docs will shape how people feel about your community. It can either feel like a locked gate or a clear, friendly path forward. Here’s how to keep them human:

• Use plain, clear language. Avoid overly complex terms, and explain acronyms if needed.

• Be specific. “You must be in the Discord server to vote” is better than “participation is required.”

• Keep it short and easy to read. Use lists, headings, and bullet points.

• Explain the “why.” Give more context. People are more likely to trust rules when they understand why they exist.

• Use examples or scenarios. For example, “when two maintainers disagree on a technical direction...”

• Make it feel open. Invite contributors to ask questions or suggest changes, including to governing procedures. That alone can help your community evolve with less friction.

How to Start Documenting Governing Procedures for Your Open Source Community

I’ve helped document governance in projects where things had been informal for years. The hardest part? Starting. There’s always a fear of overstepping or “making it too official.”

But writing things down doesn’t have to mean locking them in stone. In fact, the best governance docs are living documents, created with the community, reviewed regularly, and updated as the project grows.

Some lessons I’ve learnt:

• Start small. Even a bulleted list in a README is better than nothing.

• Use your community’s questions as your guide. If people keep asking, “how do I become a maintainer?” write that down.

• Let people review and comment. Co-create – don’t just impose.

If you’re not sure where to begin, look to open-source projects that have done this well. For example, Kubernetes has a well-structured governance model documented in its community repository, outlining everything from roles to decision-making processes.

The Tor Project also maintains transparent and community-driven governance documentation (a project I had the opportunity to contribute to) that defines roles, responsibilities, and decision-making pathways that are communicated to contributors all over the world.

Conclusion

Documenting governance doesn’t have to be scary. It’s just about making the invisible visible and doing it in a way that invites people in. When you write down how things work, you make space for others to contribute confidently, understand the community they’re joining, and grow within it. That’s what governance should be about.

So if your project doesn’t have its governing principles documented yet, don’t wait for it to get “big enough.” Start now, start small, and let it evolve with your community.

And remember: governance isn’t about control. It’s about clarity.

Begin with open source. That's what I typically tell them.

It might sound intimidating at first, but open source is one of the most accessible and welcoming ways to learn by doing. You don’t need to be an expert. You don’t need to know how to code extensively. You just need to be willing to write, research, ask questions, and contribute.

In this article, I'll share what I've learnt from my own experience with starting a career in technical writing through open source.

Table of Contents

• Common Misconceptions About Technical Writing

• Who is a Technical Writer?

• What is Open Source?

• Why You Should Build Your Technical Writing Career with Open Source

• Your Role in Open Source as a Technical Writer

• Technical Skills You’ll Need to Get Started

• How to Build a Technical Writing Portfolio Through Open Source

• After Contributing, What’s next?

• Wrapping Up

Common Misconceptions About Technical Writing

Before we get into it, let’s get some misconceptions about technical writing out of the way.

“You don’t need to know how to code.”

This is simply not true. While you do not need to be a software engineer to write excellent documentation, understanding basic technical concepts is important, especially if you want to communicate effectively with developers or document complex tools.

That said, many technical writers, myself included, get to learn on the job. You can start with what you know and build your skills from there. The key skill is not necessarily coding – it’s being able to explain things clearly and ask the right questions.

“It’s just about writing things down clearly.”

It’s more than that. Technical writing is about understanding how something works, figuring out what users need to know, and then organising that information in a way that’s useful and accessible.

It involves research, asking questions, testing things out, and often working closely with developers or product teams. The real skill lies in turning complexity into clarity – not just in writing well, but in thinking clearly and structuring information in a way that helps people succeed.

“You need a technical writing degree or certification.”

Also false. While a course or certification can help you build confidence, they’re not required. Many people get started by contributing to open-source documentation, building a portfolio, and learning on the job. Your work speaks for itself, and open source gives you the opportunity to build that body of work publicly.

“Technical writing is boring.”

Not at all. Sure, you’re not writing fiction, but you are solving problems, helping people, and building bridges between developers and users. Every sentence you write could help someone figure something out faster or feel less frustrated. That’s real impact.

Having addressed that, let's proceed.

Who is a Technical Writer?

Technical writers are the bridge between engineers and everyone else. We make the complex things read more simply, and our work appears in documentation, tutorials, API references, onboarding guides, and more.

As a technical writer, how well you explain things may affect how people use a product, how developers get started, and how whole communities evolve. Good documentation is essential for adoption, and businesses seek writers who can explain technical information with the right empathy and structure.

A good technical writer does more than just write well. They listen, research, and think critically. Some of the core skills you’ll need as a technical writer include:

• Clarity and structure in writing: Being able to explain things simply and logically.

• Curiosity and a willingness to learn: Asking questions, exploring tools, and digging into unfamiliar concepts.

• Empathy for the user: Understanding what people need and how they think.

• Basic technical understanding: You don’t need to be a programmer, but being comfortable with tools, processes, or basic code reading helps you explain technical concepts better.

What is Open Source?

There are many open-source projects that power tools and technologies you might use every day and many more that power the internet. Projects like Linux, Python, Git, Wikipedia, Firefox, WordPress, and freeCodeCamp are open source projects.

Open source refers to the practice of making a project’s inner workings – whether it’s software, hardware, content, or research – openly available for anyone to view, use, modify, and improve.

Fundamentally, open source rests on several powerful principles:

• Transparency: Anyone can inspect the project, understand how it works, learn from it, and contribute to it. Nothing is hidden.

• Collaboration: People from all over the world can contribute, suggest improvements, and solve problems together.

• Community-driven innovation: Progress happens through shared effort. The best ideas often emerge when diverse contributors come together.

Open source is about creating things in the open, together.

Why You Should Build Your Technical Writing Career with Open Source

To get started in technical writing, you need three things: a tool to document, an audience to write for, and a platform to share your work. Open source gives you access to all three and more.

Let’s talk about why contributing to open source is a powerful way to start and grow your technical writing career.

First of all, it can give you some great real-world experience. You get hands-on practice with documentation for actual tools and products used by real developers and users – not just hypothetical or practice projects.

Second, contributing to open source can help you develop your skills. From writing technical guides to improving onboarding flows, you’ll strengthen both your writing and technical understanding.

It also helps you build your portfolio, visibility, and credibility. Your contributions become a tangible way to showcase your skills in writing and working on different types of documentation projects.

Your public work, which is seen by maintainers, contributors, and even recruiters, can also help you build a reputation in the field.

Contributing also helps you develop skills in cross-functional collaboration. You’ll often work alongside developers, designers, and other members of the product team, just like a real job.

As a technical writer, your involvement also helps you gain insights into how they think and develop software, which improves your writing for technical audiences.

In addition to practicing what you already know, there will be many opportunities for you to learn new skills as well. If you’d like to learn new things while being hands-on, open-source is a great place for that. By working on open-source projects, you can gain hands-on experience with new tools, documentation platforms, and even programming languages.

You also get to meet so many people who are willing to mentor, review your work, and offer feedback, so you don’t grow in isolation.

And finally, you get to make a real impact. Good documentation empowers the people you’re writing for. Your writing could be the reason someone else joins a project or starts using a new tool.

You’re not just writing docs. You’re making technology more accessible, communities more welcoming, and learning more equitable.

Your Role in Open Source as a Technical Writer

In open source, technical writers play a crucial role in making projects usable, accessible, and scalable.

As a technical writer, your contributions might include:

• Writing and improving documentation: From installation guides to API references, you help users get started and stay unblocked.

• Creating onboarding resources: You make it easier for new contributors to join by documenting project structure, workflows, and best practices.

• Clarifying technical concepts: You turn complex ideas into clear, accessible language for users of varying skill levels.

• Organising content: You help structure docs logically so users can find what they need without frustration.

• Spotting gaps: You ask important questions like, 'What’s missing?’ What’s unclear? What would I need to know as a first-time user?

Beyond writing, you become an advocate for the user’s perspective, identifying friction points, promoting clarity, and shaping the overall user experience of a project.

Your role extends beyond mere documentation – it’ll also involve bridging the gap between creators and users and helping open source communities grow by making their work more accessible to everyone.

Technical Skills You’ll Need to Get Started

You don’t need to be a developer to contribute as a technical writer in open source, but having a few foundational skills will make your journey smoother and more impactful.

The core technical skills to focus on include:

Git & GitHub/GitLab

Version control is essential in open source. Learn how to clone repositories, create branches, make commits and submit pull requests (PRs). These are the basic workflows for contributing to projects and collaborating with others.

Here’s a handbook that’ll teach you all the Git fundamentals you’ll need in your day-to-day routine.

Markdown

Markdown is the most common format for writing open source documentation. It’s simple and lightweight, used to add structure like headings, bullet points, code blocks, links, and images to documentation.

Here’s a cheat sheet that’ll teach you markdown basics – it’s geared towards technical writers.

Basic Command Line

Knowing how to navigate folders, run simple commands, and install tools from the terminal can help you test software and understand the context you're writing about.

You can learn about command line and bash scripting basics in this detailed tutorial.

And here’s a handbook that covers some of the most commonly used Linux commands you’ll need to know.

Text Editors

Tools like VS Code, Cursor, or even online editors on GitHub are commonly used to write and edit documentation. Knowing how to work in them will make your contributions easier.

You can learn how to use VS Code, one of the most popular editors among devs, in this crash course.

Reading Code

You don’t need to be a programmer, but being able to skim through code and understand file structures or function names can help when documenting how something works.

You don’t need to master everything before you start. These are skills you’ll need to develop along the way. The most important thing is to be curious, ask questions, and keep learning as you contribute.

How to Build a Technical Writing Portfolio Through Open Source

Open source is one of the most effective ways to build a strong, public portfolio and kickstart your career as a technical writer. Here’s a step-by-step guide to help you begin contributing to open source as a technical writer:

Create a GitHub (and optionally GitLab) account

Most open source projects are hosted on GitHub, so this is your gateway to finding and contributing to them. Make sure your profile is complete and professional – consider it to be your public résumé.

Here’s a peek at what a good GitHub profile can look like (it’s mine 🤗), with a clear bio, current work, interests, and ways to connect. You don’t need to overthink it – just make sure it reflects who you are and what you’re working on.

Explore documentation-focused opportunities

Look for repositories tagged with labels like documentation, good-first-issue, or help wanted. These typically signal that certain tasks (issues) are accessible to new contributors and often related to improving or creating documentation.

Some examples of open-source projects that are known to be welcoming to documentation contributors include Mautic, GitHub, Mozilla, Layer5, Kubernetes, etc.

You can also browse communities like Hashnode, Dev.to, or Reddit’s r/opensource for leads on projects seeking writing support.

Start with simple contributions

Ease into the process by tackling small but valuable tasks like fixing typos or grammar errors, enhancing clarity and structure, and improving formatting or consistency.

These types of edits help you learn the contribution workflow and gain confidence. As you grow more comfortable, take on larger tasks, like writing tutorials, onboarding guides, or reorganising documentation systems.

Engage with project maintainers

Before making changes, introduce yourself by opening an issue or commenting on an existing one. Ask if you can work on a specific improvement, and clarify expectations around style, tone, or structure.

Good communication shows respect for the project and increases the likelihood your contribution will be accepted.

Document your work as you go

For every contribution you make, keep track of it. Create a personal documentation portfolio with links to pull requests or merged contributions, screenshots or before-and-after comparisons, and explanations of what you improved and why.

This portfolio serves as compelling evidence of your skills and impact, which can be beneficial for job applications, freelance work, or community recognition.

After Contributing, What’s next?

Once you’ve started making contributions, you’re no longer “aspiring” – you’re already doing the work. That’s something to celebrate. But it’s also just the beginning. Here’s how to keep the momentum going and turn your contributions into a foundation for growth:

Reflect on what you’ve learned

After my first few open source contributions (fixing some formatting and clarifying contributing guides), I realized how much I learned just by navigating the repo, reading through issues, and figuring out how to submit a PR.

I wasn’t just improving docs. I was learning Git and understanding community norms. Ask yourself: What did you enjoy? What was tricky? What would you do differently next time?

Ask for feedback

Don’t be afraid to reach out to maintainers or fellow contributors. Thoughtful feedback can sharpen your writing, improve your collaboration skills, and help you grow faster.

I often left comments like: “Hey! I’ve submitted a small change to improve clarity in this section. I’d love your feedback on whether the tone and structure align with your existing style guide.”

Every time I did, I either got affirmation, or helpful advice, and both helped me grow faster.

Stay involved in the community

Contributing once is wonderful. But staying active, participating in discussions, joining meetings, or helping other newcomers deepens your understanding and strengthens your place in the project.

Contribute again (and again)

Look for other areas in the same project or explore new ones. As you gain experience, try tackling more complex documentation tasks or helping shape the docs strategy.

Share your journey

Document your experience through blog posts, tweets, or videos. Sharing showcases your work and inspires others to contribute.

I’ve written blog posts and Twitter threads reflecting on my learning process, not just to celebrate but to document what I did and help others who are a few steps behind me. Almost every time I published something on learning about open-source, someone reached out to say it helped them or ask questions.

You might be the nudge someone needs to start contributing too.

Join writing communities

Get connected with other writers through groups like Write the Docs, the Hackmamba community, or even local writing meetups. These communities offer support, resources, and new opportunities.

Turn it into a career

Use your contributions as a portfolio to apply for internships, fellowships, or junior tech writing roles. Pitch your writing to developer-focused blogs or publications like freeCodeCamp. And start freelance work for startups or open-source organisations.

Technical writing has so many paths – full-time roles, freelancing, developer education, content strategy, documentation engineering – and the work you do in open source can lead to any of them.

Keep learning

Technical writing is a skill you can continue to refine through courses, peer reviews, mentorship, and hands-on practice. You can explore new tools or pick up a little code; do whatever helps you grow.

Wrapping Up

Your first contribution proves that you can write for real-world tools, collaborate in technical spaces, and add value to communities. What comes next is up to you, but you’ve already taken the most important step: you’ve started.

Have questions or want to share your journey?
I’d love to hear from you. Feel free to connect or reach out to me on LinkedIn.