Merge lp:~julian-edwards/maas/doc-improvements into lp:~maas-committers/maas/trunk

[Julian Edwards]

Fix some problems in the documentation;
 - Correct references to filing bugs and contacting the team
 - How to contribute to documentation
 - Correct juju environments.yaml
 - wrong package name on dpkg-reconfigure

[Jeroen T. Vermeulen (jtv)]

Nice polish, thanks. Some notes as you'd expect:

docs/about.rst...

19 +If you see something wrong with this documentation, you can fix it by
20 +downloading the source to MAAS by following the instructions in :doc:`the
21 +hacking guide <hacking>` and proposing a merge against lp:maas on
22 +Launchpad. The documentation source lives in the top-level ``doc/`` directory.

That's a bit much for one sentence: "you can fix problems by downloading the source by following the downloading and hacking instructions and proposing a merge." Note two levels of "by." I would suggest shorter sentences:

    If you see something wrong with this documentation, you can help us
    fix it. Download the source to MAAS following the instructions in
    :doc:`the hacking guide <hacking>`, make your changes, and propose a
    merge against lp:maas on Launchpad.

docs/juju-quick-start.rst...

36 +**Note**: You do not need to use the MAAS web UI or API to pre-allocate
37 +a node to yourself, Juju will do this for you.

The "pre-allocate" makes this very specific to what you think the reader might be thinking. I find it a bit confusing from the perspective of a reader who isn't making that mistake: "pre-allocate? Why would I want to pre-allocate? Isn't regular allocation enough?"

I'd just say "allocate" there.

Also in docs/juju-quick-start.rst...

52 Substitute the API key from earlier into the ``${maas-api-key}``
53 +slot, and the hostname of your MAAS server into the ``${my-maas-server}``
54 slot.

The <random string here> may also need explaining, if only to give the user a bit of confidence that we really do mean a random string, and this isn't some kind of l33t-speak placeholder for something we meant to document later. Maybe use the same notation that you also used for these other substitutions? Or would that become too involved?

review: Approve

[Julian Edwards (julian-edwards)]

Cheers, all good points. It seems
that while I can proof-read others',
I am useless at proof-reading my
own prose!

=== modified file 'docs/about.rst'
--- docs/about.rst	2012-11-20 21:46:37 +0000
+++ docs/about.rst	2013-08-06 05:40:36 +0000
@@ -31,5 +31,17 @@
 
 If you have some extra information to add, or think you have spotted
 an error or something out of date, we really want to hear about
-it. File a bug report or contact us via the MAAS homepage at
-http://maas.ubuntu.com
+it.  Please `File a bug report`_ or `contact us directly`_.  In addition
+you can talk to us on the Freenode IRC channel #maas.
+
+.. _File a bug report:
+  https://bugs.launchpad.net/maas/+filebug
+
+.. _contact us directly:
+  https://launchpad.net/~maas-maintainers/+contactuser
+
+If you see something wrong with this documentation, you can help us fix it.
+Download the source to MAAS by following the instructions in
+:doc:`the hacking guide <hacking>`, make your changes, and propose a merge
+against lp:maas on Launchpad.  The documentation source lives in the top-level
+``doc/`` directory.

=== modified file 'docs/juju-quick-start.rst'
--- docs/juju-quick-start.rst	2013-06-05 10:44:25 +0000
+++ docs/juju-quick-start.rst	2013-08-06 05:40:36 +0000
@@ -21,8 +21,11 @@
 One hard and fast rule is that you'll need to use a different API key
 for each Juju *environment* you set up within a single MAAS cluster.
 
-You'll also need to add an SSH key to MAAS so that you, and Juju, can
-SSH into freshly provisioned machines.
+There is no need to explicitly add an SSH key to MAAS when using Juju;
+it will automatically put your public key on any hosts that it starts up.
+
+**Note**: You do not need to use the MAAS web UI or API to allocate
+a node to yourself, Juju will do this for you.
 
 
 Getting a key
@@ -59,13 +62,18 @@
   environments:
     maas:
       type: maas
-      maas-server: 'http://localhost/MAAS'
+      maas-server: 'http://${my-maas-server}:80/MAAS'
       maas-oauth: '${maas-api-key}'
-      admin-secret: 'nothing'
+      admin-secret: ${your-admin-secret}
+      default-series: precise
 
 Substitute the API key from earlier into the ``${maas-api-key}``
+slot, and the hostname of your MAAS server into the ``${my-maas-server}``
 slot.
 
+The ``${your-admin-secret}`` slot should be replaced with a random pass-phrase,
+there is no default.
+
 
 Now Juju
 --------

=== modified file 'docs/troubleshooting.rst'
--- docs/troubleshooting.rst	2013-06-07 16:26:25 +0000
+++ docs/troubleshooting.rst	2013-08-06 05:40:36 +0000
@@ -98,7 +98,7 @@
 If you made a mistake during setup or you just need to reconfigure your MAAS
 server, you can simply run the setup again:
 
-    ``sudo dpkg-reconfigure maas``
+    ``sudo dpkg-reconfigure maas-region-controller``
 
 
 **Can't find MAAS webpage**