doc: style fixes and links

2019-12-13 15:08:02 +01:00
parent 08086ee66e
commit dea72cbe3a
10 changed files with 86 additions and 73 deletions
@@ -1,9 +1,9 @@
-Backup that Database!
-=====================
+Let's Backup that Database!
+===========================

 **Junior**

-  A Backup? Don't you have this kind of things already automated?
+  A Backup?  Don't you have this kind of things already automated?

 **Senior**

@@ -11,8 +11,8 @@ Backup that Database!
  project team ask us for a backup every time a project is finished.

  I've already prepared a script to do the task.  Before executing it in
-  production, :download:`download it <./materials/backup_db.sh>` and test it in
-  your own machine.
+  production, why don't you :download:`download it <./materials/backup_db.sh>`
+  and test it in your laptop?

  .. code-block:: console

@@ -23,7 +23,7 @@ Backup that Database!

  (after a few minutes)

-  OK, done!  When I executed it the output says:
+  OK, done!  I just run it and I got this output:

  .. code-block:: console

@@ -35,9 +35,9 @@ Backup that Database!

  That's right.  That script performed the backup and stored it into the
  **Backup Server** and appended some information into the backup log file at
-  ``/tmp/backup_db.log``.
+  :file:`/tmp/backup_db.log`.

-  Now you can ``ssh`` into the **Corporate Server** and make the real
+  Now you can :program:`ssh` into the **Corporate Server** and make the real
  backup.


@@ -57,22 +57,21 @@ Backup that Database!

 **Senior**

-  I am the only one allowed to ``ssh`` into the **Corporate Server**, for
+  I am the only one allowed to :program:`ssh` into the **Corporate Server**, for
  obvious reasons.

 **Junior**

-  Why do you need to ``ssh`` in the first place?  Couldn't it be done without
-  ``ssh``?
+  Why do you need to :program:`ssh` in the first place?  Couldn't it be done
+  without :program:`ssh`?

 **Senior**

  Actually, it could be done with a promising new tool I've just found...
  *Kapow!*

-  Is a tool that allows you to publish scripts as ``HTTP`` services.  If we
-  use it here we can give them the ability to do the backup whenever
-  they want.
+  Is a tool that allows you to publish scripts as `HTTP` services.  If we use it
+  here we can give them the ability to do the backup whenever they want.

 **Junior**

@@ -92,10 +91,10 @@ Backup that Database!

 **Senior**

-  Don't worry, it is pretty easy.  Basically we will provide an ``HTTP``
-  endpoint managed by *Kapow!* at the **Corporate Server**; when the project
-  team wants to perform a backup they only need to call the endpoint and
-  *Kapow!* will call the backup script.
+  Don't worry, it is pretty easy.  Basically we will provide an `HTTP` endpoint
+  managed by *Kapow!* at the **Corporate Server**; when the project team wants
+  to perform a backup they only need to call the endpoint and *Kapow!* will call
+  the backup script.

 **Junior**

@@ -116,11 +115,11 @@ Backup that Database!

 **Junior**

-  Done! But it doesn't do anything.
+  Done!  But it doesn't seem to do anything...

 **Senior**

-  Now you have the port ``8080`` open but don't have any endpoints defined.
+  Now you have the port ``8080`` open, but no endpoints have been defined yet.
  To define our endpoint you have to run this in another terminal:

  .. code-block:: console
@@ -140,7 +139,8 @@ Backup that Database!

  Not at all.  The creators of *Kapow!* have thought of everything.  You can put
  all your route definitions in a special script file and pass it to the server
-  on startup.  They call those files `pow` files and they have ``.pow`` extension.
+  on startup.  They call those files :file:`pow` files and they have
+  :file:`.pow` extension.

  It should look something like:

@@ -180,11 +180,11 @@ Backup that Database!

 **Junior**

-  Yay!  I can see the log file at ``/tmp/backup_db.log``
+  Yay!  I can see the log file at :file:`/tmp/backup_db.log`

 **Senior**

-  That's great.  I am going to install all this in the *Corporate Server* and
+  That's great.  I am going to install all this in the **Corporate Server** and
  forget about the old procedure.

  That enough for your first day!  Go home now and get some rest.
@@ -3,16 +3,16 @@ What have we done?

 **Senior**

-  Ey, I come from seeing our project team mates.  They're delighted with their
+  Hey, I come from seeing our project team mates.  They're delighted with their
  new toy, but they miss something.

  I forgot to tell you that after the backup is run they need to review the log
-  file to check that all went OK.
+  file to check that everything went OK.

 **Junior**

  Makes sense.  Do you think that *Kapow!* can help with this?  I have the
-  feeling that this is the right way to do it...
+  feeling that this is the right way to go about it...

 **Senior**

@@ -27,7 +27,7 @@ What have we done?

 **Senior**

-  Yeah, the team is used to :command:`cat`` the log file contents to see what
+  Yeah, the team is used to :command:`cat` the log file contents to see what
  happened in the last execution:

  .. code-block:: console
@@ -38,7 +38,7 @@ What have we done?

 **Junior**

-  Let me try add this to our ``pow`` file:
+  Let me try add this to our :file:`pow` file:

  .. code-block:: console

@@ -47,7 +47,7 @@ What have we done?
 **Senior**

  Looks good to me, clean and simple, and it is a very good idea to use ``GET``
-  here as it wont change anything in the server.  Restart *Kapow!* and try it.
+  here as it wont change anything in the server.  Let's restart *Kapow!* and try it.

 **Junior**

@@ -56,4 +56,4 @@ What have we done?

 **Senior**

-  Agree.  We are done for the day with this...
+  Agreed.  And with this, I think we are done for the day...
@@ -53,7 +53,7 @@ We need to filter
       | kapow set /response/body'

  It looks a bit weird, but we'll have time to revise the style later.  Please
-  make some tests on your laptop before we publish it on the *Corporate Server*.
+  make some tests on your laptop before we publish it on the **Corporate Server**.
  Remember to send them an example URL with the parameters they can use to
  filter and limit the amount of lines they get.

@@ -16,7 +16,7 @@ I Need my Report!

 **Junior**

-  Oh. That sounds... fun.  OK, tell me about this report.
+  Oh.  That sounds... fun.  OK, tell me about this report.

 **Senior**

@@ -184,11 +184,11 @@ I Need my Report!

 **Senior**

-  There is a better way.  You can make use of another neat ``bash`` feature:
-  **group commands**.
+  There is a better way.  You can make use of another neat :command:`bash`
+  feature:  `command grouping`_.

-  Group commands allows you to execute several commands treating the
-  group as one single command.
+  Command grouping allows you to execute several commands treating the group as
+  one single command.

  You can use this way:

@@ -226,3 +226,5 @@ I Need my Report!
  You know me.  Whatever it takes to avoid writing reports ;-)

  (both chuckle).
+
+.. _command grouping: https://www.gnu.org/software/bash/manual/html_node/Command-Grouping.html
@@ -64,7 +64,7 @@ Sharing the Stats

 **Senior**

-  See it for yourself.
+  See for yourself.

  .. code-block:: console

@@ -170,7 +170,7 @@ Sharing the Stats

 **Senior**

-  You are right, but you are not using ``HTTP`` correctly.  You have to set the
+  You are right, but you are not using `HTTP` correctly.  You have to set the
  ``Content-Type`` header to let your client know the format of the data you are
  outputting.

@@ -227,5 +227,5 @@ Sharing the Stats

 **Senior**

-  That's perfect!  Now, let's upload this to the *Corporate Server* and tell the
+  That's perfect!  Now, let's upload this to the **Corporate Server** and tell the
  frontend developer about it.