Docs Workshop Repo

This docs repository was created with AsciiBinder. For more information on how AsciiBinder works, check out the documentation.

How to Work with the Repo

1. Make sure you have an account on pagure.io and that you have uploaded your SSH key to the account. See First Steps on pagure.

2. Fork the repo to your pagure.io namespace (click the Fork button in the top-right corner of this repo's main page).

3. Clone the repo to your machine:
   git clone ssh://git@pagure.io/forks/<username>/fedora-docs/flock2017-docs-workshop.git

4. Change to the en-US/sysadmin_user_stories/ directory.

5. Start hacking on assemblies and modules. See the Modular Documentation Reference Guide, especially Chapter 3. Writing Modular Documentation.

Understanding User Story-Based and Modular Docs

This workshop is about modular documentation based on user stories. What is that?

Modular documentation is documentation based on modules, which the writer combines into assemblies (think articles). Each assembly documents a user story, which is a task description in the form of a sentence like this: As a <type of user>, I want to <goal> so that <reason>.

Simple schema of possible module combinations and reuse

+-------------------+   +-------------------+   +-------------------+
|                   |   |                   |   |                   |
|    ASSEMBLY 1     |   |    ASSEMBLY 2     |   |    ASSEMBLY 3     |
|                   |   |                   |   |                   |
|  Assembly intro   |   |  Assembly intro   |   |  Assembly intro   |
|                   |   |                   |   |                   |
| +---------------+ |   | +---------------+ |   | +---------------+ |
| |   Module A    | |   | |   Module D    | |   | |   Module G    | |
| +---------------+ |   | +---------------+ |   | +---------------+ |
| +---------------+ |   | +---------------+ |   | +---------------+ |
| |   Module B    | |   | |   Module E    | |   | |   Assembly 1  | |
| +---------------+ |   | +---------------+ |   | +---------------+ |
| +---------------+ |   | +---------------+ |   | +---------------+ |
| |   Module C    | |   | |   Module F    | |   | |   Module H    | |
| +---------------+ |   | +---------------+ |   | +---------------+ |
|                   |   | +---------------+ |   |                   |
|  Additional res.  |   | |   Module C    | |   |  Additional res.  |
|                   |   | +---------------+ |   |                   |
+-------------------+   |                   |   +-------------------+
                        |  Additional res.  |
                        |                   |
                        +-------------------+

For a thorough explanation, description of different types of modules, and real-world examples, see the Modular Documentation Reference Guide.

Previewing the Docs

1. Make sure you have Asciidoctor installed:
   # dnf install asciidoctor

2. Run asciidoctor on the index.adoc file in the repo's root:
   $ asciidoctor index.adoc

3. Open the resulting HTML file in a browser of your choice:
   $ <browser-of-choice> index.html

Submitting Your Contribution

You have added some docs to the repo and verified the book preview. How do you share your work? Use the standard workflow:

1. Push to the work branch in your fork.

2. Open a pull request against the original Docs Workshop Repo.