From 8adf51890a208e48dc9ca7e67c3d74ff2c200934 Mon Sep 17 00:00:00 2001
From: Eeshan Garg <jerryguitarist@gmail.com>
Date: Thu, 28 Sep 2017 18:03:38 -0230
Subject: [PATCH] bots/xkcd: Improve and refactor doc.md to use Markdown
 macros.

This commit does the following:
* Minor improvements to the writing wherever possible.
* Replace links to screenshots with links that would work when
  rendering said screenshots on the main repo. This would mean
  the screenshots won't be rendered outside the main repo.
* Adds a section that links to our Bots Guide's How to run a bot
  tutorial by using a Markdown a macro.
---
 zulip_bots/zulip_bots/bots/xkcd/doc.md | 53 +++++++++++++-------------
 1 file changed, 26 insertions(+), 27 deletions(-)

diff --git a/zulip_bots/zulip_bots/bots/xkcd/doc.md b/zulip_bots/zulip_bots/bots/xkcd/doc.md
index 6f666e1..f2d0662 100644
--- a/zulip_bots/zulip_bots/bots/xkcd/doc.md
+++ b/zulip_bots/zulip_bots/bots/xkcd/doc.md
@@ -1,40 +1,39 @@
 # xkcd bot
 
-xkcd bot is a Zulip bot that can fetch a comic strip from xkcd. To use xkcd
-bot you can simply call it with `@xkcd` followed by a command. Like this:
+xkcd bot is a Zulip bot that can fetch a comic strip from xkcd. To use
+the xkcd bot, you can simply call it with `@xkcd` followed by a command,
+like so:
 
 ```
 @xkcd <command>
 ```
 
-xkcd bot has four commands:  
+{!running-a-bot.md!}
 
-1. `help`  
-This command is used to list all commands that can be used with this bot.
-You can use this command by typing `@xkcd help` in a stream.  
-![](assets/xkcd-help.png)
+## Usage
 
-2. `latest`  
-This command is used to fetch the latest comic strip from xkcd. You can use
-this command by typing `@xkcd latest` in a stream.  
-![](assets/xkcd-latest.png)
+The xkcd bot has four commands:
 
-3. `random`  
-This command is used to fetch a random comic strip from xkcd. You can use
-this command by typing `@xkcd random` in a stream, xkcd bot will post a
-random xkcd comic strip.  
-![](assets/xkcd-random.png)
+1. `help` - This command is used to list all commands that can be used
+   with this bot. Example usage: `@xkcd help`:
+   ![](/static/generated/bots/xkcd/assets/xkcd-help.png)
 
-4. `<comic_id>`  
-To fetch a comic strip based on id, you can directly use `@xkcd <comic_id>`,
-for example if you want to fetch a comic strip with id 1234, you can type
-`@xkcd 1234`, xkcd bot will post a comic strip with id 1234.  
-![](assets/xkcd-specific-id.png)  
+2. `latest` - This command is used to fetch the latest comic strip from
+   xkcd. Example usage: `@xkcd latest`:
+   ![](/static/generated/bots/xkcd/assets/xkcd-latest.png)
 
-If you type a wrong command to xkcd bot, xkcd bot will post information
-you'd get from `@xkcd help`.  
-![](assets/xkcd-wrong-command.png)
+3. `random`- This command is used to fetch a random comic strip from xkcd.
+   Example usage: `@xkcd random`:
+   ![](/static/generated/bots/xkcd/assets/xkcd-random.png)
 
-And if you type a wrong id, xkcd bot will post a message that an xkcd comic
-strip with that id is not available.  
-![](assets/xkcd-wrong-id.png)
+4. `<comic_id>` - To fetch a comic strip based on ID, you can supply the
+   ID to the bot as a parameter (`@xkcd <comic_id>`). For example, if you
+   want to fetch a comic strip with ID 1234, type `@xkcd 1234`:
+   ![](/static/generated/bots/xkcd/assets/xkcd-specific-id.png)
+   If the ID requested doesn't exist, the bot will post a message that
+   the comic strip associated with that ID is not available, like so:
+   ![](/static/generated/bots/xkcd/assets/xkcd-wrong-id.png)
+
+5. If you type a command that isn't recognized by the bot, it will respond
+   the information printed by the `@xkcd help` command:
+   ![](/static/generated/bots/xkcd/assets/xkcd-wrong-command.png)