From 1fcddecda413ee5bccfd8b1451864170164c5d2c Mon Sep 17 00:00:00 2001 From: Aneta Šteflová Date: Aug 23 2017 13:21:32 +0000 Subject: Handout: 1 new question, a few fixes --- diff --git a/README.adoc b/README.adoc index c402b2c..77f05bb 100644 --- a/README.adoc +++ b/README.adoc @@ -19,7 +19,7 @@ $ git clone ssh://git@pagure.io/fedora-docs/flock2017-docs-workshop.git + The repo holds a modular guide we will be contributing to. + -* Make sure you have an account on *pagure.io* and that you have uploaded your SSH key to the account. +* Make sure you have an account on *pagure.io* and that you have uploaded your SSH key to the account. See link:https://docs.pagure.org/pagure/usage/first_steps.html[First Steps on pagure]. + * Install *asciidoctor*. + @@ -29,7 +29,7 @@ The repo holds a modular guide we will be contributing to. + * Browse this link:https://rkratky.fedorapeople.org/moddocs/[Modular Documentation Reference Guide], especially _Chapter 3. Writing Modular Documentation_. -.What does modular documentation look like? +.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 , I want to so that ._ @@ -38,17 +38,21 @@ image::modules_assemblies.png[] // Robert, I added the image to the root repo dir. I didn't know where else to put it, feel free to move it somewhere else. // The rest makes sense only for handouts *at* the workshop. -.I've chosen a module that I want to write. What do I do exactly? +.I have chosen a module that I want to write. What do I do exactly? -. Open the corresponding placeholder file we've created in the repo. For example: `flock2017-docs-workshop/en-US/procedure-adding_users_to_user_groups.adoc`. +. Open the corresponding placeholder file in the repo. For example: `flock2017-docs-workshop/en-US/procedure-adding_users_to_user_groups.adoc`. . Replace the contents of the placeholder files with your docs. You can use the existing sections link:https://bex.fedorapeople.org/fedora-docs-web/f26/system-administrators-guide/basic-system-configuration/Managing_Users_and_Groups.html[Managing users and Groups] or link:https://docs.fedoraproject.org/en-US/Fedora/25/html/SELinux_Users_and_Administrators_Guide/sect-Managing_Confined_Services-MariaDB-Configuration_Examples.html#sect-Managing_Confined_Services-MariaDB-Configuration_Examples-Changing_Database_Location[MariaDB Changing Database Location]: browse through them and pick the pieces that fit your module. -.I've added some docs to the repo, and now I want to see the whole book. How do I preview it? +.I have added some docs to the repo, and now I want to see the whole book. How do I preview it? TBD // Robert, can you please add this? I don't know if people should use asciidoctor, asciibinder, or what. +.I have added some docs to the repo and verified the book preview. How do I share my work? + +Use the standard workflow: push to a branch in your fork and open a pull request. + == License image:http://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg["Creative Commons License",height=31px,width=88px]