DC/OS Documentation

Documentation for the Datacenter Operating System (DC/OS)

These documents are used as source to generate dev.dcos.io/docs (staging and internal to Mesosphere) and dcos.io/docs (production). They are submoduled into dcos-website for deployment.

**Issue tracking is moving to the DCOS JIRA documentation component.

Contributing

If this is your first contribution to an open source software (OSS) project, congratulations! Contributing to the documentation is a great way to get started. By following these instructions you can learn more about DC/OS, and contribute back to an OSS project right away. No expertise necessary!

This page provides instructions on how to contribute to the DC/OS documentation. The process ensures that work is not duplicated, and that your contributions are merged and approved by the admins. To get started you need a GitHub account and an account on the DC/OS JIRA.

• Making your contribution
• Styling and formatting your contribution
• Building and testing your content locally

Making your contribution

Overview

1. Create a fork.
2. Clone your forked repo locally (e.g. git clone git@github.com:<your-username>/dcos-docs.git).
3. Create a branch (.e.g. git checkout -b <your-name>/<your-branch-name>
4. Make your changes.
5. Commit your changes (e.g. git commit -am "These are my changes").
6. Push your changes upstream (e.g. git push origin <your-name>/<your-branch-name>).
7. Submit a pull request to dcos-docs.

Detailed

1. Search JIRA to review the currently open issues and make sure that no one is already working on your issue. If you find an open issue that is unassigned that you want to work, you can assign it to yourself! If you don’t see an issue related to yours, create a new issue, select documentation as the component, and assign it to yourself.

   

2. If this is your first contribution Fork the dcos-docs repo. (Once you’ve forked the repo, that fork stays associated with your GitHub account. If you try to fork it again GitHub will remind you that you already have a fork.)

3. Create a local repository, or if you already have one make sure it is up to date.

   • If this is your first contribution, go to your terminal, navigate to the directory where you keep your Git projects, and clone your fork of the dcos-docs repo.

     git clone https://github.com/<your-user-name>/dcos-docs

   • If this isn't your first contribution check out the master branch

      git checkout master

     and update it by following these instructions.

4. Create a new branch of your local repository using your JIRA number as the name. This way other contributors can find the JIRA issue that descirbes the goal of your contribution.

   git checkout -b dcos-nnn

5. Create your content.

   • In most cases you should be able to create your content within the existing directory structure.
   • If you're not sure how to add formatting, take a look at dcos.io/docs for examples.
   • Be sure you follow the style and formatting guidelines in the next section.
   • Don't forget to update your post's metadata if necessary, including the required metadata post_title and optional nav_title and menu_order. Where applicable, add the optional feature_maturity label. Description of various feature maturity phases can be found here.

   The metadata should be at the very top of the post's file, and look something like this:

   ---
   post_title: This is how you update the documentation
   nav_title: Update Docs
   menu_order: 5
   feature_maturity: preview
   ---
   The rest of your document's text will go here, underneath the second set of dashes.
   

6. When you're happy with your improvements, build a local copy of the website by following these instructions to make sure that everything looks good, and that nothing is broken.

7. Push your changes into the feature branch of your remote repository on github.com.

   1. First, add your changes (this gets them ready to be included in your commit).

      git add .

   2. Next commit the changes you made to your local branch, and add a useful message so that everyone knows what you've changed.

      git commit -m "Addresses issue DCOS-nnn. More useful stuff here"

   3. Finally push your changes up to your remote branch on GitHub, so that you can open a pull request.

      git push origin dcos-nnn

8. Submit a pull request against the dcos-docs repo.

   • Don't forget to add a link to this PR in your JIRA issue.
   • Community managers will test drive and validate contributions that include hands-on instructions, and they'll probably ask for improvements or modifications by commenting on your PR. If you agree with their changes make them in your local repo and repeat steps 5-7 above, or feel free to continue the discussion.

Styling and formatting your contribution

• Use GitHub-flavored markdown.
• Use relative links.
  • Begin all links at the root docs level and include the version number subdirectory. (e.g., /docs/1.8/administration/sshcluster/).
• For links that end with parenthesis, you must use the HTML code ) for the closing parenthesis. For example, this link [Shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) should instead be [Shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)).
• Do not include file extensions in your link or image paths. For example, the directory /docs/1.8/administration/ contains a file named user-management.md. To link to this content on the live site, you would use the following path: /docs/1.8/administration/user-management/.
• Each directory must contain an index.md file. This acts as the base-level topic for each folder in the site (required).
• The table of contents of each page is automatically generated based on the top-level headers.
  • Directory tables of contents are automatically generated based on post_title (or nav_title) and post_excerpt headers.
• Use active voice whenever possible.
• Use sentence-style capitalization for headings.

In addition to the above technical notes, make sure you read your doc for clarity and accuracy. Pretend you are someone else seeing your instructions for the first time, and try to follow them based only on the information you provided.

Screenshots

• We should always use a more realistic cluster name and user name (e.g. not joel-master-ee- or Bootstrap User).
• For the browser window, we should stick with a standard resolution (1440x900) and be consistent with it across all screenshots, unless we are intentionally cropping in on a key area of the window.
• For the browser window, we should strip all browser chrome, bookmarks, user-specific extensions, themes, etc. You can easily hide this without having to remove them.
• Don’t zoom in/out on your browser. This creates weird styling issues.
• Be careful of focus. For example, be careful that the browser toolbar is not the focus. This causes the viewer to assume there is a reason we are focused on the address bar.
• Crop to the pixel. If you want a clean capture of the entire browser:
  • (a) lose the browser entirely and crop to the exact bounds of the UI
  • (b) use CMD+SHIFT+4 then hit SPACE then click the window you want to capture

Building and testing your content locally

Pick one of the below methods to build your changes, integrated with the rest of dcos.io, on your local machine. This makes sure that your changes don't break the docs or the website. If you're not sure which method you should use to build the website locally, we recommend the automated build, because it has fewer prerequisites and is more reliable. If you find problems with your doc, edit the file. Your local build should update every time you save your changes.

Automated build

This method builds and launches a Docker container. For more information, see this PR.

Prerequisites

Latest version of Docker installed and running.

Make command installed.

Building

1. Run make

   • Linux

   Running docker commands as a normal user in Linux requires a manual installation step to add the user to the docker group.

   If your user is already in the docker group :

   make

   If your user is not in the docker group :

   sudo make

   • MacOS

   On MacOS users can run docker commands by default

   make

   Tip: This can take up to 15 minutes to complete.

2. Visit localhost:3000

Troubleshooting

If your build fails with an error (e.g. npm ERR! /website/npm-debug.log), try deleting the /dcos-docs/tmp directory and re-running the make command.

Manual build

We've implemented the dcos-docs repo as a submodule of the dcos-website repo. Fork the parent dcos-website repo and build the site locally. This will allow you to confirm that your content renders correctly and that all of your links work. For each step, follow the instructions for your operating system.

Prerequisites

1. Ruby

   • CentOS

     sudo yum install -y ruby

   • MacOS using Homebrew

     brew install ruby

2. Git

   • CentOS

     sudo yum install git

   • MacOS using Homebrew

     brew install git

3. Install Node, and NPM.

   • CentOS

     On CentOS we need to add the epel-release repo before we can install Node and NPM

     sudo yum install -y epel-release && sudo yum install -y nodejs && sudo yum install -y npm && npm update

   • MacOS using Homebrew

     brew install -y nodejs
     brew install npm
     npm update

4. nvm 6.3.1

   • CentOS

     curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash
     nvm install 6.3.1 && nvm alias default 6.3.1

   • MacOS

     curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash
     nvm install 6.3.1 && nvm alias default 6.3.1

5. Gulp

   • CentOS

     sudo npm install --global gulp-cli

   • MacOS

     npm install --global gulp-cli

6. Clone the dcos-website repo.

   git clone https://github.com/dcos/dcos-website

7. Check out the develop branch of dcos-website.

   git checkout develop

8. Initialize the dcos-docs submodule with the content from the upstream master.

   git submodule update --init --recursive

   Optional: replace the content from the upstream master with the content from your local dcos-docs repo. Delete the dcos-website/dcos-dcos directory and replace it with a symlink to your local dcos-docs repo. For example, if your directory structure is /projects/dcos-website and /projects/dcos-docs, you can issue these commands from the dcos-website directory:

   rm -r dcos-docs
   ln -s <local-path-to-dcos-docs> dcos-docs

Building

Launch the local web server to view your changes.

npm start

License and Authors

Copyright 2017 Mesosphere, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this repository except in compliance with the License.

The contents of this repository are solely licensed under the terms described in the LICENSE file included in this repository.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Authors are listed in AUTHORS.md file.