Hello everyone,
We’re excited to announce an important change and milestone for the Snapcraft documentation, referred to on snapcraft.io as the Snapcraft build-tool.
After a great effort over the last six months and with the help of folks the community, we’ve moved the principal Snapcraft material to a new home:
documentation.ubuntu.com/snapcraft
About docs-as-code
If you’ve used other craft projects recently, you may have noticed that their documentation looks different and is hosted on the Ubuntu domain. That’s because their docs reside in the projects’ codebases and are built with Sphinx, a dedicated documentation tool. The docs are themselves versioned, and released alongside the project – in other words, what you see in the docs is what’s shipped with the code.
This arrangement is known as docs-as-code, and is a well-tested practice that we’re adopting for all products at Canonical.
Snapcraft now has its docs in the code. At the new domain, you can see that with each new version of Snapcraft that ships, there’s a corresponding version of the docs.
What’s changed in the Snapcraft docs
During the transition, we aligned the structure of the docs more closely to the Diátaxis framework. We hope that with the reorganization, you’ll have an easier time finding what you need. Wherever we could, we also improved technical accuracy and relevance of the pages.
This doesn’t mean that all work is completed on the Snapcraft docs – no documentation is ever finished. It means that it’s easier to view the state of the documentation, get input and reviews from developers and authors, and reliably make changes to the right version.
It also means that contributions to the guide are credited in the changelogs and release notes, which is something that wasn’t easy to do with Discourse. Your documentation contributions are very important to the project.
What’s next for docs on snapcraft.io
The snap daemon (snapd) documentation remains actively supported on the forum, including our snap command guides and the pages on advanced snapd features. We feel this setup provides a much clearer distinction between snap user documentation, advanced snap usage, and Snapcraft. In the coming months, we plan to migrate the remaining snapd documentation to its own docs-as-code repository, too.
Nothing’s changing about how the forum is used otherwise – it’s still the first stop for discussion about crafting snaps. The shift simply means that work on the docs will be more tightly tied to the existing development workflows on GitHub. It will result in more frequent documentation updates across the board.
If you would like to migrate some of the guides in the forum posts, or if you spot any errors, we welcome your help. I suggest you start with the contributing guide in the Snapcraft codebase and the reStructuredText style guide for Sphinx projects at Canonical.
Snapcraft also has documentation work to do in the Canonical Open Documentation Academy. Some of our best contributions sprout from requests there. If you’d like to help with docs, be sure to give it a look!
As always, you can reach out to us about documentation gaps in a post here, in a GitHub issue, or on Matrix.
Onward and upward!