Contributing to the documentation
category | meta | contributing |
---|---|---|
tags | documentation |
how to contribute to the documentation
There are several ways to contribute to the documentation:
- Ask questions and make suggestions on the forum
- Submit an issue on github
- Editing documentation pages online with github
- Advanced method: Editing offline and previewing on your computer
Ask questions and make suggestions on the forum
The forum is the place where all questions about the Sense/Stage system can be asked. So if you cannot figure out how to do something, you can ask the question there, and one of the other people on the forum will respond to your question and a discussion will start.
As users ask questions, we will find out how the documentation can be improved, and the forum builds up a repository of questions and answers that can be referred back to in the future.
If there is a particular documentation page that you want to discuss, you can name the topic accordingly and tag the topic as Documentation. For example: Suggestions for the Getting Started with Sense/Stage documentation. Then in the post itself you can make the suggestions you have for improving the documentation page. For example you can propose a text that you would like to see on the page and explain where on the page there is a mistake (and if possible how to improve it).
Some discussion on the forum will follow and either someone else will make the suggested changes to the documentation page, or file an issue on github to remember to make the changes at a later point in time.
Submit an issue
We host our documentation pages on github. By signing up with github, you can file issues that you find with the documentation.
- Sign up at github. Just sign up for the free account. Do not forget to verify your account.
- Go to the Sense/Stage documentation pages on github
- Click on the Issues tab.
- Click the green button on the top right saying New issue
- Give a clear title to the issue, for example: make a reference to the shop on the getting started page
- Describe what you would like to see changed in the documentation page. For example you can propose a text that you would like to see on the page and explain where on the page there is a mistake (and if possible how to improve it).
- After you submit the issue, other people can comment on the proposed change. One of the Sense/Stage team members will pick the issue up and make the suggested improvement to the documentation page. And close the issue once it is resolved.
Creating your own copy of the documentation pages on github
We host our documentation pages on github. By signing up with github, you can edit the documentation online and send us a message to update the webpage.
- Sign up at github. Just sign up for the free account. Do not forget to verify your account.
- Go to the Sense/Stage documentation pages on github
- Fork the repository. There is a button at the top right side, saying Fork. This will create a copy of the documentation files into your account on github.
- Navigate to the file you want to change the documentation of.
Forking in detail
Layout of the repository
The important folders where you will want to put files or change files are:
_minibee
: this is the documentation for everything around the MiniBee systemimg
: this is where images for the documentation go
Writing your contribution
Edit a page
To find the page that you want to edit, look at the URL of the documentation page. For example if you want to improve the Getting Started page, the URL is https://docs.sensestage.eu/minibee/getting-started-with-sense-stage.html
. You can then find the source file in the folder _minibee
(mirroring the /minibee
in the URL) with the filename getting-started-with-sense-stage.md
. Click on the file name. You will see a rendered version of the documentation page. If you click on the Edit button you will be able to edit the documentation page.
See the this page for the formatting of the text
Make a new page
- Go to the directory where you want to make the file. For example
_minibee
- Click on Create new file on the top right.
- The name of the page should match the title of the page you want to make. Except with
-
instead of spaces or other signs. So “Getting started with Sense/Stage” should have the file name `getting-started-with-sense-stage.md’ - Fill in the metadata of the page
- Write the page.
- Commit the change
- Inform us about the change
See this page for the formatting of the text
Upload files
Perhaps you have written a page offline, or you want to add images to the documentation
- Go to the directory where you want to make the file. For example
_minibee
orimg
- Click on Upload files on the top right
- Drag and drop files or select choose your files
- Commit the change
- Inform us about the change
For images, please make the filename of the image as descriptive as possible. So instead of image1.jpg
use connecting-a-pressure-sensor-to-a-minibee.jpg
if the image depicts how to connect a pressure sensor to a minibee. Also, don’t use spaces in the file names. So instead of connecting a pressure sensor to a minibee.jpg
use connecting-a-pressure-sensor-to-a-minibee.jpg
Seeing your contribution online
You will not see your contribution in the online documentation directly. After you have informed us (made your pull request) as described below, we will review the changes that you have made, merge your proposed changes with the official copy and render the result to html. Then we will upload the result to the website. We will let you know that we have done so by commenting on the pull request.
You can already get a preview on github itself, if the document is not in the edit mode. In this preview you will see the basic formatting of the page (italic/bold text, headers, links, embedded images), so you can already check if you the contribution is as intended. However, the final result will look slightly different.
Submitting the update
Committing the change
Once you have edited the file, you can commit the changes at the bottom of the page. You can give a description of what you changed in the documentation page; this is a reference for the future to understand the history of the changes to the document over time.
Just commit to your master branch.
Informing us about the changes you made
To tell us about the changes you made, you have to make a “Pull request”.
- Go to the tab “Pull Requests”
- Click the green button “Create a pull request”
- Github will give an overview of the changes you made.
- You can give a description of all the changes you made.
- And then click “Create pull request”.
We will then be notified about the changes, review them and merge them into the documentation. And update the website.
Congratulations! You are now a contributor to the Sense/Stage project!
Go back to your copy of the repository
- Go to your profile
- Go to your repositories
- And go the
sensestage_documentation
repository
Syncing your local copy of the repository with the latest version
At some point you might notice that the files in the main SenseStageTeam repository have been updated, while your local copy remains outdated. In order to get the latest version of the documentation files you need to do a pull request that copies over all the new files into your local fork.
-
Click the “New Pull Request” button.
This will take you to the Comparing Changes screen.. which should look something like this.
-
If the option to “Try switching the base for your comparison” is there, click that If not, switch the bases manually using the dropdown menus. Set them up so that your local fork is on the left, and the original is on the right.
-
Click the “Create pull request” button. If you want you can also scroll down and see what’s different between your files and the ones in the SenseStageTeam repository.
-
Give it a title like “updating my local copy”.
- Click the “Create Pull Request” button.
- Click the “Merge pull request” button, and after that “Confirm Merge”. You’re up to date!
Advanced methods
The documentation pages are rendered with Jekyll. You can set up Jekyll on your own system and preview the pages in your browser.
Setting up Jekyll
Jekyll itself is written in Ruby. So you need to get Ruby first.
The easies way is to use the Ruby Version Manager (RVM) first. Follow the instruction on the RVM website on how to install. Then you install the right version of Ruby (v2.1.2) and bundler
like this:
rvm install 2.1.2
rvm use 2.1.2
gem install bundler
bundle install
Cloning the git repository on your machine
- On your copy of the github repository, click Clone or download
- Copy the link given there
- Open a terminal
- Type
git clone
(with a space at the end) - Past the link you just copied on the command line after the space
- Press enter
- You may be asked for your password to your github account
- Cloning of the repository on your local machine will start
- A folder named
sensestage_documentation
will be created
Run Jekyll locally
Now you can start Jekyll on your local machine:
From sensestage_documentation
folder:
cd sensestage_documentation
bundle exec jekyll serve
And now you can browse to the local URL: http://localhost:4000 and preview the changes.
Once done, you can stop the local hosting again by pressing CTRL-C
in the terminal.
Jekyll References
Commit your changes
- Add and commit your local changes with git using the
git add
andgit commit
methods - Push your changes to your github account:
git push origin master
- Create a pull request so that we can merge your changes
Related pages:
category | meta | contributing |
---|---|---|
tags | documentation |
page created on: | last changed on: |
---|---|
26 March 2017 | 27 March 2017 |