From 1f7b7a0fe5ee80b6097eabc331f9864b3158b1f7 Mon Sep 17 00:00:00 2001 From: Aneta Šteflová Petrová Date: Aug 22 2017 14:53:55 +0000 Subject: Add first draft for workshop handout --- diff --git a/README.adoc b/README.adoc index b0497ed..7d1abb2 100644 --- a/README.adoc +++ b/README.adoc @@ -2,6 +2,57 @@ 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]. +== Workshop Handout + +// Suitable for handouts distributed around the venue *before* the workshop and *at* the workshop. +.What can I expect to get from the workshop? + +Learn what the plan is to revive Fedora docs. Learn how to contribute to a modular guide. + +.What will I accomplish by the end of the workshop? + +Make a contribution to a modular Fedora guide. + +.What should I do before going to the workshop? + +* Clone this link:https://pagure.io/fedora-docs/flock2017-docs-workshop[repo]. It holds the content we will be contributing to. ++ +---- +$ git clone ssh://git@pagure.io/forks/aneta/fedora-docs/flock2017-docs-workshop.git +---- ++ +Make sure you have an account on *pagure.io* and that you have uploaded your SSH key to the account. ++ +To contribute to the repository, push to your fork and then open pull requests. ++ +* Install asciidoctor. ++ +---- +# dnf install asciidoctor +---- ++ +* Browse this link:https://rkratky.fedorapeople.org/moddocs/[Modular Documentation Reference Guide]. + +.What does modular documentation look like? + +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 ._ + +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 describe. 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`. +. 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 assignment. + +.I've 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. + == License image:http://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg["Creative Commons License",height=31px,width=88px] diff --git a/modules_assemblies.png b/modules_assemblies.png new file mode 100644 index 0000000..7c8242f Binary files /dev/null and b/modules_assemblies.png differ