Juju User Documentation

" An undocumented feature is not a feature "

How to get documentation for your features into docs

It is useful for users to know features exist, and how to use them. Discovering functionality by exploring the help topics is not really ideal. In order to get better, relevant documentation for users, the docs team needs to know that the feature actually exists, and how it is supposed to work. The best way to make this happen is for you to let them know what is happening, and hopefully provide some useful notes on it.

What is user documentation?

At a minimum, we should strive to give users accurate information on what Juju can do, and how commands etc. are expected to work. This would include a brief summary of what the feature is expected to do and why it may be useful, accompanied by good examples showing a range of possible uses. To help structure this information, there is now a template in the docs repository on github: docs template

For an example, see the current storage docs: https://jujucharms.com/docs/devel/wip-storage

Where do I put user documentation?

Depending on what is being documented, the ultimate resting place for the information may be in several different places in the current documentation, but YOU DO NOT NEED TO WORRY ABOUT THAT.

You just need to:

• Fork the docs on github (https://github.com/juju/docs)
• Read the Contribs page for notes on format and style (https://jujucharms.com/docs/stable/contributing)
• Use the template to create a new work-in-progress page
• Write things
• Create a pull request for your branch
• That's it

The docs team will look at the page you created. They may have questions, but they will make sure it gets added to the devel version of the docs ASAP. They will add it to the navigation, and at such a point as the feature is live, they will make sure the information gets on the relevant pages of stable documentation.

When should I write user docs?

The earlier the better. It is actually a useful exercise in assessing your changes to the code - if you have to explain something (properly), you need to understand it, and understanding it better usually means you can make it work better. At the minimum, some notes should be available when the feature goes into testing. How can anything be tested if nobody knows it is there or how to use it? You can always go back to the docs and make changes - in fact, we encourage that.

What if I can't write?

Writing good documentation is a skill, and not one which everyone is expected to have. It doesn't matter if:

• You can't spell
• You have appalling grammar
• English is not your first language

Some of the very best contributions to docs so far come from people who fall into all three of the above categories. It doesn't matter - the docs people can do all of these things (on a good day) and will probably want to rewrite most of what you have written anyhow. You are not expected to write end user documentation, just communicate the information to someone who will.

If you don't feel you can write a description of your feature, or explain how it works, we can investigate other possibilities - perhaps you could explain it to someone on a hangout, or draw lots of diagrams or send the docs team a crate of gin. There are all sorts of options, so please get in touch.