By John Mulhausen
The documentation team at Docker is excited to announce that we are consolidating all of our documentation into a single GitHub Pages-based repository on GitHub.
When is this happening?
The new repo is public now at https://github.com/docker/docker.github.io.
During the week of Monday, September 26th, any existing docs PRs need to be migrated over or merged.
We’ll do one last “pull” from the various docs repos on Wednesday, September 28th, at which time the docs/ folders in the various repos will be emptied.
Between the 28th and full cutover, the docs team will be testing the new repo and making sure all is well across every page.
Full cutover (production is drawing from the new repo, new docs work is pointed at the new repo, dissolution of old docs/ folders) is complete on Monday, October 3rd.
The problem with the status quo
Up to now, the docs have been all inside the various project repos, inside folders named “docs/” — and to see the docs running on your local machine was a pain.
The docs were built around Hugo, which is not natively supported by GitHub, and took minutes to build, and even longer for us to deploy.
Even worse than all that, having the docs siloed by product meant that cross-product documentation was rarely worked on, and things like reusable partials (includes) weren’t being taken advantage of. It was difficult to have visibility into what constituted “docs activity” when pull requests pertained to both code and docs alike.
Why this solution will get us to a much better place
All of the documentation for all of Docker’s projects will now be open source!
It will be easier than ever to contribute to and stage the docs. You can use GitHub Pages’ *.github.io spaces, install Jekyll and run our docs, or just run a Docker command:
git clone https://github.com/docker/docker.github.io.git docs
cd docs
docker run -ti –rm -v “$PWD”:/docs -p 4000:4000 docs/docstage
Doc releases can be done with milestone tags and branches that are super easy to reference, instead of cherry-picked pull requests (PRs) from several repos. If you want to use a particular version of the docs, in perpetuity, it will be easier than ever to retrieve them, and we can offer far more granularity.
Any workflows that require users to use multiple products can be modeled and authored easily, as authors will only have to deal with a single point of reference.
The ability to have “includes” (such as reusable instructions, widgets that enable docs functionality, etc) will be possible for the first time.
What does this mean for open source contributors?
Open source contributors will need to create both a code PR and a docs PR, instead of having all of the work live in one PR. We’re going to work to mitigate any inconvenience:
Continuous integration tests will eventually be able to spot when a code PR is missing docs and provide in-context, useful instructions at the right time that guide contributors on how to spin up a docs PR and link it to the code PR.
We are not going to enforce that a docs PR has to be merged before a code PR is merged, just that a docs PR exists. That means we should be able to merge your code PR just as quickly, if not more so, than in the past.
We will leave README instructions in the repos under their respective docs/ folders that point people to the correct docs repo.
We are adding “edit this page” buttons to every page on the docs so it will be easier than ever to locate what needs to be updated and fix it, right in the browser on GitHub.
We welcome contributors to get their feet wet, start looking at our new repo, and propose changes. We’re making it easier than ever to edit our documentation!
The post Announcing the new Docs Repo on GitHub! appeared first on Docker Blog.
Quelle: https://blog.docker.com/feed/
Published by