How you can contribute!
It's a tough job writing documentation which covers every use case and scenario - mainly because Juju is so versatile it can be used in so many ways. That is why we hope to get plenty of feedback from users to help extend, amend and improve the documentation. It is really easy and you don't have to be the world's best writer. Our grammar goblins will sort out any problems with the words, but your knowledge is very useful to us.
Why aren't you using Sphinx/Pandoc/Markdown...?
Because rather than force everyone to use one system of creating/editing docs, we wanted to be more inclusive and use a pretty easy to understand, well-recognised standard which doesn't restrict what we want to do. You CAN use any of these systems to contribute docs by the way, but just use the HTML output from them to add to the current docs
How to write docs!
Contributing to the docs is really easy because it is all written in HTML5. In a very minimal way too - you will find most of the source documents are very straightforward and human-readable, if you just want to dip in and change a paragraph or add some extra info.
Below is a list of the current style conventions in use in the docs.
Text is just written using standard <p> tags
Sections
All the text is organised into sections. Each section has a heading, possibly subheadings and body text/other elements, so it looks something like this:
<section id="sectionname"> <h1>Heading for section</h1> <p>This is some stuff.</p> </section>
Each section MUST have an id. These are used as anchors, and it makes more sense to attach them to sections than individual headings. Even if you think your section will never be referenced (it will!), you should have an id="something")
Code Blocks
Instructions are wrapped in the following tags:
<pre class="prettyprint"> </pre>
Inline code
For running copy (i.e., when a command or similar appears in the middle of a paragraph) we use the following:<code>juju deploy minecraft</code>
Notes
Notes, other than asides, can be tagged as paragraphs, and begin with the word "Note:" like this:
<p class="note"><strong>Note:</strong>
It is important to use the class="note"
property for the paragraph to pick up the correct style.
Adding pages
If you find you need to add a page to the documentation, then you will also need to add it to the navigation, which means altering two additional files - navigation.html and navigation.json
For navigation.json, you will need to enter a key:value pair in the appropriate location, e.g.:
"Scaling Services": "charms-scaling.html",
Note the quote marks, position of the colon, and the comma if required (i.e. if adding a page in the middle of a list). The same entry also needs to be included in the navigation.html page:
<li class="sub"><a href="charms-scaling.html">Scaling Services</a></li>again in the appropriate section. Please make sure you submit a merge proposal with a description of the new page and why it is needed!
Testing or Deploying locally
The documentation makes use of Javascript for some functionality, so in order to test the docs properly or serve them localy, you will need to have an http server set up.
On Ubuntu this is easy. Install (if you need to) and start the apache2 web server, then just copy the htmnldocs directory to a convenient location -
sudo cp -R htmldocs /var/www/htmldocs
You can then point your web browser at your local machine (127.0.0.1/htmldocs) to view the files.
Alternatively, you can use Python to start a simple HTTP server on the docs directory. Navigate to the htmldocs directory of juju-core docs and run the following:
python -m SimpleHTTPServer
Submitting your work
We love it when the community contributes to documentation, here's how to get the code, branch it, modify it, and submit it back. First off get the code:
bzr branch lp:juju-core/docs
Then go into the docs directory:
cd docs/htmldocs
In here you'll find the HTML files that you can edit in your text editor. After we make our changes we need to commit them and push them to your place on launchpad :
bzr commit -m 'Whatever your changelog will be' bzr push lp:~jorge/juju-core/foo
Replace ~jorge
with your launchpad username and foo
with a name that describes a fix, so something like bzr push lp:~jorge/juju-core/fix-typos-in-introduction
or something. Now there's one step left, and that's to propose it for inclusion:
bzr lp-propose lp:juju-core/docs
And that's it! Someone from the Juju team will review your work and merge it in! Please don't forget to review the page before submission.