Where do open source docs go?

To start publishing open source docs, you need somewhere to put them. Here are some common approaches.

A reader recently wrote to me with a question about publishing open source documentation for the first time. Here’s a paraphrase of the question, with project-specific details omitted:

I’m starting an open source project on GitHub for the first time. I want to share planning documents, so others can see the thought process that happened before coding even started. Where should they go? Should it go in a separate branch or another repository?

Here’s my revised and expanded response.

Where docs could go

It’s tempting for open source maintainers to think of design and planning docs as a special thing, independent of user documentation. But in open source software, contributors are a kind of user and thus a kind of documentation reader. This is true even if, on day one of the project, the only contributor is you.

Thus, design and planning docs often end up in the same places that user documentation does, in Git and GitHub (or another forge). Common places to put docs in a GitHub repository are:

A README file
A top-level directory on the main branch, such as /docs/
A separate documentation repository (or, less commonly, multiple repositories for docs with different audiences)

A separate documentation branch is less common, though not unheard of. Historically, this was the only way to make a docs site with GitHub Pages.

Sometimes docs are stored outside of Git in some parallel system, such as a wiki. And many projects have informal documentation found in issues, discussion forums, Discord channels, and mailing list archives.

Where docs should go

For a new project, I recommend starting with a single repository. A new or small project often has just one or two core maintainers, but the benefit of multiple repos tends to go to larger teams with contributors who have distinct responsibilities. If you have not yet drawn lines around design, development, and documentation work and assigned those tasks to different people, multiple repositories adds the overhead cost without the reward.

In a repository, you can start from a README file alone (here’s a checklist to get started), featuring a “Development” or “Contributing” section, though you might soon outgrow it. When it gets too long, create a /docs/ folder with a contribute.md file.

As a project grows, contributing docs often appear as just one docs section among many. For example, the curl documentation has a “Developing curl” section with information about what work needs to be done, project internals, and so on.

Larger projects may split docs into separate repositories. For example, the Astro project has:

a core code repository
a roadmap repo for documenting design decisions
a docs repo for user docs
and many others, including a meta documentation repo

each representing distinct domains and often distinct groups of maintainers and contributors. This is probably a bit much for most projects (it’s perhaps a bit much for any project), but it’s also not set in stone. Astro didn’t start out with all those different repositories. Like the Astro team, you can split things up into different repos, if and when the time comes.

Where docs ought not go

There are a few places where you can put docs where you probably shouldn’t.

Avoid a separate docs branch. For new users and collaborators, non-default branches are especially difficult to discover. The source itself also becomes difficult for you to search and modify: your editor’s search won’t find its contents (without switching branches first) and you won’t be able to change docs and code in the same pull request.

Regard wikis with distrust. Wikis tend toward disorganized messes more swiftly than plaintext files tracked in Git. Consistent editorial attention can overcome this; you will probably know if you have the resources to do this.

Likewise, avoid relying solely on informal docs, such as a Discord Q&A or discussion forums. Informal docs will appear—that’s normal. But orienting yourself around such tools often means those docs are hidden from web searches and difficult to migrate out of, if you ever change your mind.

Get started

My correspondent asked one more question: when should I publish on GitHub? For this part, you’ve got to follow your heart.

I like to start a Git repository as early as possible, committing and pushing often. It takes a little bit of bravery to work in public like this, but it also means that you have more opportunities to bring in collaborators and users. Because everything is in the open from the start, working this way also means never having to confront the worry “is this good enough to publish yet?”

Admittedly, that’s easy for me to say—through my work, I have a lot of practice working in public—so you might want to wait until you have reached an important milestone, but consider picking that milestone in advance, so you can’t talk yourself out of publishing forever.