Juju documentation

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.

How to write docs!

Contributing to the docs is really easy because it is all written in GitHub flavored Markdown. 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. The Juju docs use a modified version of the Github Flavored Markdown to compose the content of the docs. We've retained the majority of GFM, with the exception of "Username linking" and "Emoji", both of which are Github specific.

In addition to the removals, we've also created several new Markdown definitions to implement features required for the docs. These definitions are outlined below.

Grab the docs and get to work

The code is available on github.com/juju/docs. Clone it, edit it, and then submit a pull request.

We enforce 80 columns for every text file to keep it readable. Here are instructions for two editors:

Here is a handy Markdown reference) to get you started, and don't forget to reference the GitHub Flavored Markdown reference.

The individual document pages are in the src directory. From there each language is seperated into it's own directory by language code. So for example English is in src/en.

Sections

All the text is organised into sections. These are autogenerated, there is nothing extra you need to do:

# <h1> equivalent
## <h2> equivalent
### <h3> equivalent

Code Blocks

To code block something indent each line with 4 whitespace characters.

Inline code

Use a backtick to inline commands and other literals.

Notes, Warnings, Callouts, Admonishments

Callouts are used to notify the user of additional information or warn them of potential pitfalls. This will create a notification resembling the following in the docs:

callout

To implement this callout, use the following syntax:

!!! Note: If you want to get more information on what is actually happening, or to help resolve problems, you can add the `--show-log` switch to the juju command to get verbose output.

Foldouts

When a page contains a high volume of information that would otherwise require a table of contents, or similar method of quick navigation, a foldout can be used. This will create a collapsed header which, when clicked, will expand to display all the content below it.

^# Header
  Content can be multi-paragraphed and will be sent through the Markdown parser

  As long as content is continually indented under the header

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 one file, src/navigation.tpl.

Add the page with the following format:

<li class="sub"><a href="charms-scaling.html">Scaling Services</a></li>;

in the appropriate section. Please make sure you submit a merge proposal with a description of the new page and why it is needed!

Adding Screenshots

When adding screenshots place them in htmldocs/media. To reference them in your page use the syntax ![description](media/picture.png)

Testing or Deploying locally

First you need to generate the docs from the Markdown. In the root directory first get the dependencies and make the docs:

make sysdeps
make

Note: You only need to make sysdeps once, after that you'll have all the dependencies you'll need to build the docs going forward.

The documentation makes use of Javascript for some functionality, so in order to test the docs properly or serve them localyl, 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 the docs and run the following:

python -m SimpleHTTPServer

Submitting your work

We love it when the community contributes to documentation, here's how to contribute:

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.