From 0bb4af6ea2c92a0ffebd1498bdb1eb158ea6842f Mon Sep 17 00:00:00 2001 From: Jacob Walser Date: Mon, 14 Jan 2019 22:00:21 -0500 Subject: [PATCH 1/2] add documentation guideline --- guidelines/documentation.md | 51 +++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 guidelines/documentation.md diff --git a/guidelines/documentation.md b/guidelines/documentation.md new file mode 100644 index 0000000..6a20e06 --- /dev/null +++ b/guidelines/documentation.md @@ -0,0 +1,51 @@ +# Documentation + +## General Recommendations + +- Be mindful that we have many users worldwide. Use language that translates and instructs well. +- Write documents that are concise and punctual. +- HyperLinks are cheap, use them! Remember to use anchors, too. +- Try to maintain one source of documentation, avoid documenting the same thing in two places. +- Use markdown for documents whenever possible. +- Use version control (git) for documents whenever possible. + +## Documentation Locations + +- [ArduPilot wiki](http://ardupilot.org/ardupilot/) + This [repository](https://github.com/ArduPilot/ardupilot_wiki) is owned and maintained by the ardupilot organization. +- [QGroundControl gitbook](https://docs.qgroundcontrol.com/en/) + This repository is owned and maintained by the mavlink organization. It is the official documentation for QGroundControl users. This is where documenation on QGroundControl usage should generally go. +- [MAVLink website](https://mavlink.io/) + This repository documents the MAVLink binary communication protocol used by QGroundControl, Companion, and ArduPilot. Here, you can find the message definitions and information about how to develop MAVLink enabled applications. +- [ArduSub gitbook](http://ardusub.com) + This repository is owned and maintained by Blue Robotics. This repository contains: + - General ArduSub firmware documentation and instructions + - Blue Robotics companion documentation + - QGC + ArduSub + companion integration and usage instructions + - Developer examples for interacting with ArduSub via MAVLink/MAVProxy +- [gh-pages](https://pages.github.com/) + + Github employs a feature called gh-pages to host project websites. The source for the website is maintained in a separate branch of the repository named `gh-pages`. If the branch exists, the website can be accessed via the url http://*username*.github.io/*repository*. Project pages in the Blue Robotics organization are also available at https://docs.bluerobotics.com/*repository*. + + gh-pages sites is a good place to host doxygen documentation for a project. + + Blue Robotics currently has the following projects with gh-pages sites: + ping-arduino + ping-python + +- Repository READMEs + + Each repository should have a README in the root directory. This README is displayed on the project's home page. The README should contain information about what the project is, what it does, and how to use it. CI status information should be added to the top of the README. Additional READMEs may exist in project subdirectories, which will be displayed when the directory is opened in github. + +- Blue Robotics documentation + + The Blue Robotics wordpress website has documentation pertaining to Blue Robotics products, and is targeted at Blue Robotics customers. This is where *product* documentation should go. There are three tabs of interest for the product documentation: + - Description: High level product description and features + - Technical Details: Specifications, drawings, models and datasheets + - Learn: Educational resources, documentation, instructions, example usage and tutorials + + If the product is related to one or more software projects, the product *Learn* tab should link out to the software documentation. + + +- This repository + This repository contains guidelines on how we develop things at Blue Robotics. Preferred methods and development tools may also be described here, as well as tips and tricks. From 79232ea3bc34db7bfb39ec7aef39de25661bed84 Mon Sep 17 00:00:00 2001 From: Jacob Walser Date: Tue, 2 Apr 2019 08:28:44 -0400 Subject: [PATCH 2/2] fixup! --- guidelines/documentation.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/guidelines/documentation.md b/guidelines/documentation.md index 6a20e06..bcbc233 100644 --- a/guidelines/documentation.md +++ b/guidelines/documentation.md @@ -2,27 +2,28 @@ ## General Recommendations -- Be mindful that we have many users worldwide. Use language that translates and instructs well. -- Write documents that are concise and punctual. -- HyperLinks are cheap, use them! Remember to use anchors, too. -- Try to maintain one source of documentation, avoid documenting the same thing in two places. -- Use markdown for documents whenever possible. -- Use version control (git) for documents whenever possible. +- Be mindful that we cater to users and enthusiasts from many countries and languages. Use language that translates well, and avoid idioms +- Write documents that are concise and punctual +- Use markdown for documents whenever possible; don't use special/plugin formatting. Markdown is preferred because it is lightweight and portable among hosting/templating platforms +- [hyperlinks](https://en.wikipedia.org/wiki/Hyperlink) are cheap, use them! Use markdown anchors to refer to section headings. Both are easy to use with markdown +- Try to maintain one source of documentation, avoid documenting the same thing in two places +- Use version control (git) for documents whenever possible +- All Blue Robotics documentation patches should be peer reviewed, just like code ## Documentation Locations -- [ArduPilot wiki](http://ardupilot.org/ardupilot/) - This [repository](https://github.com/ArduPilot/ardupilot_wiki) is owned and maintained by the ardupilot organization. -- [QGroundControl gitbook](https://docs.qgroundcontrol.com/en/) - This repository is owned and maintained by the mavlink organization. It is the official documentation for QGroundControl users. This is where documenation on QGroundControl usage should generally go. -- [MAVLink website](https://mavlink.io/) - This repository documents the MAVLink binary communication protocol used by QGroundControl, Companion, and ArduPilot. Here, you can find the message definitions and information about how to develop MAVLink enabled applications. - [ArduSub gitbook](http://ardusub.com) This repository is owned and maintained by Blue Robotics. This repository contains: - General ArduSub firmware documentation and instructions - Blue Robotics companion documentation - QGC + ArduSub + companion integration and usage instructions - Developer examples for interacting with ArduSub via MAVLink/MAVProxy +- [ArduPilot wiki](http://ardupilot.org/ardupilot/) + This [repository](https://github.com/ArduPilot/ardupilot_wiki) is owned and maintained by the ardupilot organization. It contains documentation for ardupilot generally, as well as documentation for the other ardupilot vehicles (copter, plane, rover, but not ArduSub). +- [QGroundControl gitbook](https://docs.qgroundcontrol.com/en/) + This repository is owned and maintained by the mavlink organization. It is the official documentation for QGroundControl users. This is where documenation on QGroundControl usage should generally go. +- [MAVLink website](https://mavlink.io/) + This repository documents the MAVLink binary communication protocol used by QGroundControl, Companion, and ArduPilot. Here, you can find the message definitions and information about how to develop MAVLink enabled applications. - [gh-pages](https://pages.github.com/) Github employs a feature called gh-pages to host project websites. The source for the website is maintained in a separate branch of the repository named `gh-pages`. If the branch exists, the website can be accessed via the url http://*username*.github.io/*repository*. Project pages in the Blue Robotics organization are also available at https://docs.bluerobotics.com/*repository*. @@ -30,12 +31,13 @@ gh-pages sites is a good place to host doxygen documentation for a project. Blue Robotics currently has the following projects with gh-pages sites: - ping-arduino - ping-python + [ping-viewer](https://docs.bluerobotics.com/ping-viewer) + [ping-arduino](https://docs.bluerobotics.com/ping-arduino) + [ping-python](https://docs.bluerobotics.com/ping-python) - Repository READMEs - Each repository should have a README in the root directory. This README is displayed on the project's home page. The README should contain information about what the project is, what it does, and how to use it. CI status information should be added to the top of the README. Additional READMEs may exist in project subdirectories, which will be displayed when the directory is opened in github. + Each repository should have a README in the root directory. This README is displayed on the project's home page. The README should contain information about what the project does, how to install it, and how to use it. CI status information should be added to the top of the README. Additional READMEs may exist in project subdirectories, which will be displayed when the directory is opened in github. - Blue Robotics documentation @@ -46,6 +48,5 @@ If the product is related to one or more software projects, the product *Learn* tab should link out to the software documentation. - - This repository - This repository contains guidelines on how we develop things at Blue Robotics. Preferred methods and development tools may also be described here, as well as tips and tricks. + This repository contains guidelines on how we develop things at Blue Robotics. Preferred methods, processes and development tools may also be described here, as well as tips and tricks.