Docs Workshop Repo

This docs repository was created with http://asciibinder.org/[AsciiBinder]. For more information on how AsciiBinder works, check out the http://asciibinder.org/latest/[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>. See a module and assemblies schema.

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 -a toc -n index.adoc

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