Where docs are stored can impact open source projects in a variety of ways. This talk will present some options, considerations, and guidelines for making an informed decision when choosing a path for docs in current and future projects.
Deciding where to store documentation, particularly for open source projects, can raise a number of questions. Do users or contributors need to read the docs offline? Do you keep a docs record for older versions, and if so, how and where do you store them, and how do you handle new releases? Is there a point where documentation content, versioning, style, and assets become too unweildy to store with code?
As a documentarian working on a number of open source projects, as well as providing site deployment support to even more, I’ve seen and tried a variety of strategies to answer these questions. I’ll share a handful of successful approaches, how they came about, and the pros and cons of each. Audience members will leave with guidelines for choosing the best “path” for docs in current and future open source projects.
This talk will look at process-type aspects (like considerations for reducing contributor friction), and the OSS tooling that can help address some of these considerations. All of it is in the context of documenting and working with open source projects.
As an example, you might decide that the actual docs website (generated with an open source site generator) is too bulky to store in the code repo (impacting clone times for new contributors). On the other hand, you might want to keep the text content of the docs in the code repo, because they can be accessed offline after cloning, and code-updating PRs can easily include corresponding docs updates. One option for handling this dual-repo setup is an open source tool called Markdown Magic, which can run during the site generator build, and pull marked content from code comments or markdown files in the main repo. I've actually used this setup myself, and can speak from experience about some of the conveniences, inconveniences, and gotchas to watch out for when using that tool/strategy.
Speakers: Jessica Parsons