Documentation file naming cleanup

Part of https://issues.apache.org/jira/browse/MESOS-3686 Clean up of filenames in documentation, prefer hyphens and drop 'mesos' from filenames This closes: #70 Review: #70
apache · Oct 9, 2015 · b29ec4f · b29ec4f
1 parent e8e9768
commit b29ec4f
Show file tree

Hide file tree

Showing 19 changed files with 60 additions and 21 deletions.
diff --git a/docs/mesos-architecture.md → docs/architecture.md b/docs/mesos-architecture.md → docs/architecture.md
diff --git a/docs/mesos-c++-style-guide.md → docs/c++-style-guide.md b/docs/mesos-c++-style-guide.md → docs/c++-style-guide.md
diff --git a/docs/clang-format.md b/docs/clang-format.md
@@ -6,7 +6,7 @@ layout: documentation
 
 [ClangFormat](http://llvm.org/releases/3.5.1/tools/clang/docs/ClangFormat.html) is an automatic source code formatting tool which helps us focus on the code rather than the formatting.
 
-> The provided configurations try to honor the [Mesos C++ Style Guide](http://mesos.apache.org/documentation/latest/mesos-c++-style-guide/) as much as possible, but there are some limitations which require manual attention. Even with these limitations however, ClangFormat will be extremely useful for your workflow!
+> The provided configurations try to honor the [Mesos C++ Style Guide](http://mesos.apache.org/documentation/latest/c++-style-guide/) as much as possible, but there are some limitations which require manual attention. Even with these limitations however, ClangFormat will be extremely useful for your workflow!
 
 ## Setup
 

diff --git a/docs/mesos-containerizer.md → docs/containerizer.md b/docs/mesos-containerizer.md → docs/containerizer.md
diff --git a/docs/documentation-guide.md b/docs/documentation-guide.md
@@ -0,0 +1,37 @@
+# Mesos Documentation  Guide
+
+Documentation is an integral part of every good feature. It describes the intended usage and enables new users to start using and understanding the feature.
+
+We have three different kinds of documentation:
+
+
+1. [MarkDown User Guides](/documentation/latest/markdown-style-guide/)
+
+  User guides and non-code technical documentation are stored in markdown files in the `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/).
+
+  We will accept small documentation changes on [Github via a pull request](https://github.com/apache/mesos), larger documentation changes should go through the (reviewboard)[https://reviews.apache.org/groups/mesos/]
+
+
+2. [Doxygen API Documentation and Developer Guides as part of source code](/documentation/latest/doxygen-style-guide/)
+
+  Doxygen API documentation needs only to be applied to source code parts that
+  constitute an interface for which we want to generate Mesos API documentation
+  files. Implementation code that does not participate in this should still be
+  enhanced by source code comments as appropriate, but these comments should not follow the doxygen style.
+
+  Substantial libraries, components, and subcomponents of the Mesos system such as
+  stout, libprocess, master, slave, containerizer, allocator, and others
+  should have an overview page in markdown format that explains their
+  purpose, overall structure, and general use. This can even be a complete developer guide.
+
+
+3. Regular source code documentation
+
+  All other source code comments must follow the [Google Style Guide](https://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Comments).
+
+
+## Conventions
+
+We follow the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)
+on how to use words such as "must", "should", "can",
+and other requirement-related notions.
diff --git a/docs/mesos-doxygen-style-guide.md → docs/doxygen-style-guide.md b/docs/mesos-doxygen-style-guide.md → docs/doxygen-style-guide.md
diff --git a/docs/effective-code-reviewing.md b/docs/effective-code-reviewing.md
@@ -22,7 +22,7 @@ to consider before sending review requests:
    change clear in the review request, so the reviewer is not left
    guessing. It is highly recommended to attach a JIRA issue with your
    review for additional context.
-4. **Follow the [style guide](http://mesos.apache.org/documentation/latest/mesos-c++-style-guide/)
+4. **Follow the [style guide](http://mesos.apache.org/documentation/latest/c++-style-guide/)
    and the style of code around you**.
 5. **Do a self-review of your changes before publishing**: Approach it
    from the perspective of a reviewer with no context. Is it easy to figure
@@ -88,4 +88,4 @@ review process.
 6. **For reviewers, be thorough when giving a 'ship it'**: understand that
 reviewing requires a substantial investment of time and focus:
     a. You are expected to understand and support code that you're giving a 'ship it' to.
-    b. You are expected to be accountable for the quality of the code you've given a 'ship it' to.
+    b. You are expected to be accountable for the quality of the code you've given a 'ship it' to.
diff --git a/docs/mesos-frameworks.md → docs/frameworks.md b/docs/mesos-frameworks.md → docs/frameworks.md
diff --git a/docs/home.md b/docs/home.md
@@ -6,14 +6,14 @@ layout: documentation
 
 ## Mesos Fundamentals
 
-* [Mesos Architecture](/documentation/latest/mesos-architecture/) providing an overview of Mesos concepts.
-* [Video and Slides of Mesos Presentations](/documentation/latest/mesos-presentations/)
+* [Mesos Architecture](/documentation/latest/architecture/) providing an overview of Mesos concepts.
+* [Video and Slides of Mesos Presentations](/documentation/latest/presentations/)
 
 ## Running Mesos
 
 * [Getting Started](/documentation/latest/getting-started/) for basic instructions on compiling and installing Mesos.
 * [Configuration](/documentation/latest/configuration/) for command-line arguments.
-* [Mesos Containerizer](/documentation/latest/mesos-containerizer/) default containerizer, supports both Linux and POSIX systems.
+* [Mesos Containerizer](/documentation/latest/containerizer/) default containerizer, supports both Linux and POSIX systems.
 * [Docker Containerizer](/documentation/latest/docker-containerizer/) for launching a Docker image as a Task, or as an Executor.
 * [External Containerizer](/documentation/latest/external-containerizer/) for custom containerization implementations.
 * [Framework Authentication](/documentation/latest/authentication/)
@@ -27,7 +27,7 @@ layout: documentation
 * [Slave Recovery](/documentation/latest/slave-recovery/) for doing seamless upgrades.
 * [Maintenance](/documentation/latest/maintenance/) for performing maintenance on a Mesos cluster.
 * [Tools](/documentation/latest/tools/) for setting up and running a Mesos cluster.
-* [SSL](/documentation/latest/mesos-ssl/) for enabling and enforcing SSL communication.
+* [SSL](/documentation/latest/ssl/) for enabling and enforcing SSL communication.
 
 ## Advanced Features
 
@@ -40,13 +40,13 @@ layout: documentation
 
 ## Running Mesos Frameworks
 
- * [Mesos frameworks](/documentation/latest/mesos-frameworks/) for a list of apps built on top of Mesos and instructions on how to run them.
+ * [Mesos frameworks](/documentation/latest/frameworks/) for a list of apps built on top of Mesos and instructions on how to run them.
 
 ## Developing Mesos Frameworks
 
 * [Framework Development Guide](/documentation/latest/app-framework-development-guide/) describes how to build applications on top of Mesos.
 * [Reconciliation](/documentation/latest/reconciliation/) for ensuring a framework's state remains eventually consistent in the face of failures.
-* [Scheduler HTTP API](/documentation/latest/scheduler_http_api/) describes the new HTTP API for communication between schedulers and the Mesos master.
+* [Scheduler HTTP API](/documentation/latest/scheduler-http-api/) describes the new HTTP API for communication between schedulers and the Mesos master.
 * [Javadoc](/api/latest/java/) documents the Mesos Java API.
 * [Doxygen](/api/latest/c++/namespacemesos.html) documents the Mesos C++ API.
 * [Developer Tools](/documentation/latest/tools/) for hacking on Mesos or writing frameworks.
@@ -60,17 +60,17 @@ layout: documentation
 
 * [Reporting an Issue, Improvement, or Feature](/documentation/latest/reporting-a-bug/) for getting started with JIRA.
 * [Submitting a Patch](/documentation/latest/submitting-a-patch/) for getting started with ReviewBoard and our tooling around it.
-* [Testing Patterns](/documentation/latest/mesos-testing-patterns/) for tips and tricks used in Mesos tests.
+* [Testing Patterns](/documentation/latest/testing-patterns/) for tips and tricks used in Mesos tests.
 * [Effective Code Reviewing](/documentation/latest/effective-code-reviewing/) guidelines, tips, and learnings for how to do effective code reviews.
 * [Engineering Principles and Practices](/documentation/latest/engineering-principles-and-practices/) to serve as a shared set of project-level values for the community.
 * [Committing](/documentation/latest/committing/) guidelines for committing changes.
 * [Committers and Maintainers](/documentation/latest/committers/) a listing of project committers and component maintainers; useful when seeking feedback.
 * [Doxygen](/api/latest/c++/) documents the internal Mesos APIs.
-* [Documentation Guide](/documentation/latest/mesos-documentation-guide/)
-  * [C++ Style Guide](/documentation/latest/mesos-c++-style-guide/)
-  * [Doxygen Style Guide](/documentation/latest/mesos-doxygen-style-guide/)
-  * [Markdown Style Guide](/documentation/latest/mesos-markdown-style-guide/)
-* [Development Roadmap](/documentation/latest/mesos-roadmap/)
+* [Documentation Guide](/documentation/latest/documentation-guide/)
+  * [C++ Style Guide](/documentation/latest/c++-style-guide/)
+  * [Doxygen Style Guide](/documentation/latest/doxygen-style-guide/)
+  * [Markdown Style Guide](/documentation/latest/markdown-style-guide/)
+* [Development Roadmap](/documentation/latest/roadmap/)
 * [Release Guide](/documentation/latest/release-guide/)
 
 ## More Info about Mesos

diff --git a/docs/mesos-markdown-style-guide.md → docs/markdown-style-guide.md b/docs/mesos-markdown-style-guide.md → docs/markdown-style-guide.md
diff --git a/docs/mesos-documentation-guide.md b/docs/mesos-documentation-guide.md
@@ -9,6 +9,8 @@ We have three different kinds of documentation:
 
   User guides and non-code technical documentation are stored in markdown files in the `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/).
 
+  We will accept small documentation changes on [Github via a pull request](https://github.com/apache/mesos), larger documentation changes should go through the (reviewboard)[https://reviews.apache.org/groups/mesos/]
+
 
 2. [Doxygen API Documentation and Developer Guides as part of source code](/documentation/latest/mesos-doxygen-style-guide/)
 

diff --git a/docs/powered-by-mesos.md b/docs/powered-by-mesos.md
@@ -95,6 +95,6 @@ layout: documentation
 
 ## Software projects built on Mesos
 
-See the [Mesos frameworks page](mesos-frameworks.md) for a list of apps built on top of Mesos, and instructions on how to use them.
+See the [Mesos frameworks page](frameworks.md) for a list of apps built on top of Mesos, and instructions on how to use them.
 
 If you're using Mesos, please add yourself to the list above, or email user@mesos.apache.org and we'll add you!
diff --git a/docs/mesos-presentations.md → docs/presentations.md b/docs/mesos-presentations.md → docs/presentations.md
diff --git a/docs/mesos-roadmap.md → docs/roadmap.md b/docs/mesos-roadmap.md → docs/roadmap.md
diff --git a/docs/scheduler_http_api.md → docs/scheduler-http-api.md b/docs/scheduler_http_api.md → docs/scheduler-http-api.md
diff --git a/docs/mesos-ssl.md → docs/ssl.md b/docs/mesos-ssl.md → docs/ssl.md
diff --git a/docs/submitting-a-patch.md b/docs/submitting-a-patch.md
@@ -30,10 +30,10 @@ layout: documentation
 
 ### Create your patch
 1. Create one or more test cases to exercise the bug or the feature (the Mesos team uses [test-driven development](http://en.wikipedia.org/wiki/Test-driven_development)). Before you start coding, make sure these test cases all fail.
-    1. The [testing patterns](mesos-testing-patterns.md) page has some suggestions for writing test cases.
+    1. The [testing patterns](testing-patterns.md) page has some suggestions for writing test cases.
 
 2. Make your changes to the code (using whatever IDE/editor you choose) to actually fix the bug or implement the feature.
-    1. Before beginning, please read the [Mesos C++ Style Guide](mesos-c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it.
+    1. Before beginning, please read the [Mesos C++ Style Guide](c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it.
     2. Most of your changes will probably be to files inside of `BASE_MESOS_DIR`
     3. From inside of the root Mesos directory: `./bootstrap` (Only required if building from git repository).
     4. To build, we recommend that you don't build inside of the src directory. We recommend you do the following:
@@ -77,4 +77,4 @@ layout: documentation
 4. The last step is to ensure that the necessary documentation gets created or updated so the whole world knows about your new feature or bug fix.
 
 ## Style Guides
-* For patches to the core, we ask that you follow the [Mesos C++ Style Guide](mesos-c++-style-guide.md).
+* For patches to the core, we ask that you follow the [Mesos C++ Style Guide](c++-style-guide.md).
diff --git a/docs/mesos-testing-patterns.md → docs/testing-patterns.md b/docs/mesos-testing-patterns.md → docs/testing-patterns.md
diff --git a/docs/tools.md b/docs/tools.md
@@ -20,10 +20,10 @@ These tools make it easy to set up and run a Mesos cluster.
 
 If you want to hack on Mesos or write a new framework, these tools will help.
 
-* [clang-format](/documentation/latest/clang-format/) to automatically apply some of the style rules dictated by the [Mesos C++ Style Guide](/documentation/latest/mesos-c++-style-guide/).
+* [clang-format](/documentation/latest/clang-format/) to automatically apply some of the style rules dictated by the [Mesos C++ Style Guide](/documentation/latest/c++-style-guide/).
 * [Go Bindings and Examples](https://github.com/mesosphere/mesos-go) Write a Mesos framework in Go! Comes with an example scheduler and executor.
 * [Mesos Framework giter8 Template](https://github.com/mesosphere/scala-sbt-mesos-framework.g8) This is a giter8 template. The result of applying this template is a bare-bones Apache Mesos framework in Scala using SBT for builds and Vagrant for testing on a singleton cluster.
 * [Scala Hello World](https://gist.github.com/guenter/7471695) A simple Mesos "Hello World": downloads and starts a web server on every node in the cluster.
 * [Xcode Workspace](https://github.com/tillt/xcode-mesos) Hack on Mesos in Xcode.
 
-Can't find yours in the list? Please submit a patch, or email user@mesos.apache.org and we'll add you!
+Can't find yours in the list? Please submit a patch, or email user@mesos.apache.org and we'll add you!