Dec 21, 2017
Stephanie Bodoff
D2iQ
4 min read
When we originally open sourced Mesosphere DC/OS 18 months ago we created a new documentation site for open source DC/OS, dcos.io/docs, so that it would be clear which documentation applied to DC/OS open source, and which applied to DC/OS Enterprise. The enterprise documentation is essentially a superset of the open source docs, plus additional documentation on the features available in DC/OS Enterprise.
Over the last 18 months, we've observed the shortcomings of that approach: community members are confused about where to find which docs, maintaining two sites creates extra overhead, and Google searches don't rank either docs site highly because the content is split. Users commonly look for documentation using Google search and poor rankings are an often-mentioned nuisance for both our open source and enterprise users. So, today, we're announcing a combined version of the documentation at docs.mesosphere.com, where dcos.io/docs will redirect.
The combined site has many advantages:
- Users won't have to wonder whether the documentation they're looking at applies to DC/OS open source or DC/OS Enterprise.
- Contributions will automatically apply to both the open and enterprise documentation.
- Over time, Google search results will improve.
We've completely revamped the design and implementation of the documentation site to make sure that it's clear which docs apply to DC/OS open source and DC/OS Enterprise, and have improved a number of functional aspects of the site along the way.
New Site Features
The new Mesosphere documentation site is located at docs.mesosphere.com, where the old DC/OS Enterprise site was previously. That site now contains the combined content of the old Enterprise and open source documentation. dcos.io/docs now redirects to the new site.
Documentation Home Page
Along with a fully refreshed design, we've added a slew of features to help you find what you're looking for.
Using the links at the top of the header you can easily navigate to the docs for DC/OS itself, Mesosphere-supported services, and the support site. Below the header you will see links to different sections of the docs for the latest version of DC/OS. We'll get to search later in this post.
DC/OS Docs Sidebar
When you click a link on the home page, the topic you selected will appear, along with a navigation sidebar on the left of the page.
The sidebar navigation is very similar to the old site. If you're using an older version of DC/OS you can select it with the version picker drop-down menu at the top of the sidebar and then navigate using the sidebar, which stays in your selected version. As an added bonus, we improved redisplay performance while navigating between pages using the sidebar.
Service Docs Sidebar
To look at service-related documentation, you click Service Docs in the top header links, choose a service, and then expand the menu of docs for your version of that service by selecting it in the sidebar. Here's what the Cassandra home page looks like:
In-Page Navigation
A row of icons lets you share, download (PDF), print, and contribute to the docs. You can also find links to the DC/OS community Slack channel and Jira in case you'd like to file a bug report or give us feedback:
Each page also features a two-level, scrollable table of contents at the top right so you can rapidly jump to between subsections of the page you are on to find the information you need:
DC/OS Enterprise and Open Source Identifiers
Content that applies only to DC/OS Enterprise or DC/OS open source is identified by Enterprise and Open Source badges, respectively. A badge can apply to an entire page, a section, a list item, or a table row. For example, here's a tile pointing to a child topic, Creating secrets, in the Secrets section:
If there is no badge, the content applies to both DC/OS Enterprise and open source.
Dramatically Improved On-site Search
We worked hard to improve on-site search because it is the most common way people look for specific documentation. You can quickly and easily search all the documentation using the big center field on the home page or the field found in the top right of each page.
The new site is fully indexed and now includes code snippets, so you can easily locate code referencing configuration parameter names and strings such as marathon.l4lb.thisdcos.directory. Unlike the old docs site, search results are returned with snippets, and drop-down menus on the results page allow you to refine by DC/OS or service version, Enterprise or open source, and so on.
Community Contributions
Community contributions to the open source documentation site have been really valuable, and it was important to us that the new documentation remained open source. You can find and contribute to the new repo at https://github.com/mesosphere/dcos-docs-site. We anticipate that, with our team's focus on a single documentation site, we will be much faster at reviewing PRs. For information on how to contribute, see https://github.com/mesosphere/dcos-docs-site/wiki/Contributing. We'll be adding a deprecation notice to https://github.com/dcos/dcos-docs so please send all PRs to the new site's repo, and enjoy the new DC/OS docs experience!
