Good quality documentation has been a high priority for us since we began open sourcing Cofoundry, initially building our documentation using the GitHub wiki feature.
The wiki was quick for us to get started with and get documentation out there without having to think too much about how it was organized or presented, however as we've grown we've started to feel the limitations of the service and have decided to migrate the docs on to cofoundry.org to give us more control of how our docs are organized and presented.
The new home for Cofoundry documentation is:
Still open source
The markdown source files are still open source and the docs repository is still hosted on GitHub. The new repository is here:
We've also open sourced our documentation generator which you can find on GitHub, but we'll probably write more about how that all works at a later date.
Why migrate from GitHub
Versioning
Although it is possible add tags to the wiki repository, there's no way to switch between tags in the UI. With our new docs generator we're able to create a set of documentation for each release, which you can switch between using the links in the sidebar.
We'll start versioning from this point forward so expect to see the links show up in the site when v0.6 is released.
Redirects
Redirects are not supported in GitHub wikis, so if we re-organize the docs or remove a page we can't redirect in-bound links to a new version.
In our new docs site we've implemented a redirect system and we'll also be able to detect when documentation links are broken.
Organization
GitHub doesn't give you much control over the navigation structure of your wiki, it's all rather flat. We've got over 50 pages now in our docs and it was starting to get difficult to manage.
Our new structure supports organizing pages into folders and a tree-like navigation structure with auto-generating index pages. We also have breadcrumb links and a responsive navigation menu for an improved experience.
Control
The best things is that if we haven't got it quite right or there are ways for us to improve the experience then we can now do something about it, so do let us know your feedback.
We hope you enjoy the new docs!