[documentation-guide] Added by jwulf
Joshua Wulf
jwulf at fedoraproject.org
Wed Jun 15 11:59:19 UTC 2011
commit ecc0d7070b1e103120f69a8c46dfef1a356eb56d
Author: Joshua Wulf <jwulf at redhat.com>
Date: Wed Jun 15 17:54:35 2011 +1000
Added by jwulf
en-US/Author_Group.xml | 5 +
en-US/Documentation_Guide.xml | 2 +
en-US/problem-solution-spaces.xml | 70 ++++++++++
en-US/sect-Task-Procedure-Process-Definition.xml | 70 ++++++++++
...sk-Procedure-Process-Documenting-Procedures.xml | 16 ++
...ask-Procedure-Process-Documenting-Processes.xml | 43 ++++++
...-Procedure-Process-Example-Procedure-Source.xml | 145 ++++++++++++++++++++
...ct-Task-Procedure-Process-Example-Procedure.xml | 92 +++++++++++++
...Procedure-Process-Four-Parts-of-a-Procedure.xml | 26 ++++
...cedure-Process-Procedure-Writing-Guidelines.xml | 122 ++++++++++++++++
10 files changed, 591 insertions(+), 0 deletions(-)
---
diff --git a/en-US/Author_Group.xml b/en-US/Author_Group.xml
index a698e3f..48c6420 100644
--- a/en-US/Author_Group.xml
+++ b/en-US/Author_Group.xml
@@ -14,5 +14,10 @@
<surname>Smith</surname>
<email>jsmith at fedoraproject.org</email>
</author>
+ <author>
+ <firstname>Joshua</firstname>
+ <surname>Wulf</surname>
+ <email>jwulf at redhat.com</email>
+ </author>
</authorgroup>
diff --git a/en-US/Documentation_Guide.xml b/en-US/Documentation_Guide.xml
index 7643316..a8f6b0e 100644
--- a/en-US/Documentation_Guide.xml
+++ b/en-US/Documentation_Guide.xml
@@ -10,10 +10,12 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="workflow.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="docbook.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="writing-procedures.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="publican.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="style.xml"/>
+
<!-- Revision history -->
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<index />
diff --git a/en-US/problem-solution-spaces.xml b/en-US/problem-solution-spaces.xml
new file mode 100644
index 0000000..1630229
--- /dev/null
+++ b/en-US/problem-solution-spaces.xml
@@ -0,0 +1,70 @@
+<chapter>
+ <title>What are we writing about again?</title>
+
+ <para>
+ All technology is a solution to a problem.
+ </para>
+ <para>
+ The earliest technologies were solutions to the most basic problems - how do I get something to eat? How do I get somewhere to sleep? How to I stop someone from taking my place to sleep and my thing to eat?
+ </para>
+
+ <para>
+ Technologies introduced to solve these basic problems lead, themselves, to further problems, which require further technologies to solve. The spear requires the shield. The shield requires the mace. The mace requires the firearm. When one local store gets electronic funds transfer at the point of sale (EFTPOS), everyone else has to get it to stay competitive. When the local pizza store gets an internet portal to allow customers to order online, everyone else has to get one too. In this way, technology becomes increasingly complex, until we finally arrive at the system administrator pulling his hair out at 5pm on a Friday because he can't figure out why there are intermittent timeouts on the production SAN.
+ </para>
+
+ <para>
+ One thing to keep clearly in focus through all of this, however, is that <emphasis>all technology is a solution to a problem</emphasis>. Modern technology solves increasingly abstracted problems, many of them problems that addresses problems that arise from another technological layer underneath, but when you trace them all back down, it comes to: getting paid, so that you can get something to eat and somewhere to sleep.
+ </para>
+
+ <para>
+ Technical documentation exists to support the work of a technology's end-users. End-users approach documentation to help them solve a problem. Technical documentation exists to help users solve problems in two distinct spheres: to help them solve their business problems using the technology, and to help them solve the problems they are having using the technology.
+ </para>
+
+ <section>
+ <title>Problem spaces and Solution spaces</title>
+ <para>
+ <firstterm>Business problems</firstterm> are the challenges in the environment that the technology seeks to address. For example: an LDAP server seeks to address the problem of registering and authenticating the members of a large organisation. An EFTPOS terminal seeks to address the problem of paying for goods and services without having to convert electronic funds to paper currency. These problems in the environment constitute the <firstterm>problem space</firstterm>. Remember, all technology is a solution to a problem - and the problem that the technology aims to solve exists in the problem space.
+ </para>
+
+ <formalpara>
+ <title>Problem space</title>
+ <para>The challenges and opportunities in the environment that technology addresses.</para>
+ </formalpara>
+
+ <para>
+ Each specific technology addresses a problem in its own unique way. A Tomcat server is implemented differently from an Apache cgi-bin module, although they both address a similar business problem: "how do I make an application available in a web browser". A given technological solution to a business problem gives rise to a technology-specific <firstterm>solution space</firstterm>.
+ </para>
+
+ <formalpara>
+ <title>Solution space</title>
+ <para>The characteristics of a technology solution</para>
+ </formalpara>
+
+ <para>
+ Technical documentation aims to reduce user uncertainty. Users approach technology to generate a solution to their problem space. In doing so they encounter another problem space in the solution space itself. Recall that each technology brings with it further complexity - a further set of problems: "<para>Now that I have this whizz bang technology that will solve all my problems - how do I use it?</para>"
+ </para>
+
+ <para>
+ Comprehensive technical documentation addresses both the user problem space and technology solution space. Problem-space-focused documentation answers the end-user's question "<emphasis>how do I...?</emphasis>" when it relates to the user's domain. It is documentation for "<emphasis>when you know what you want to do, but don't know what does it</emphasis>". A problem-space-focused document related to networking might contain sections such as: "<emphasis>Sharing music with your PS3 over the network</emphasis>". Solution-space-focused documentation describes the operation of the technology. Solution-space-focused documentation is documentation for "<emphasis>when you know what technological component you need to use, and you want to know how to use it</emphasis>". A solution-space-focused version of the our example networking documentation would have a section entitled: "<emphasis>Configuring a DLNA client</emphasis>".
+ </para>
+
+ , and now the user has a solution, as well as an additional problem: "How do I use this thing?"
+ </para>
+
+ <para>
+ Technical documentation aims to take users from a state of uncertainty to a state of certainty: from "I don't know..." to "I know".
+ </para>
+
+ <para>
+ Information in technical documentation can be divided into three classes: Concept, Task, and Reference information. These classes of information answer the questions: "What's the problem? How do I solve it? Any further details?".
+ </para>
+
+ <section>
+ <title>Concept material</title>
+ <para>
+ Concept material in documentation answers the question: "<emphasis>What's the problem?</emphasis>". This material describes the problem space. It is employed by end-users in two ways:
+ </para>
+ <orderedlist>
+ <listitem><para>To learn more about the technology
+
+
diff --git a/en-US/sect-Task-Procedure-Process-Definition.xml b/en-US/sect-Task-Procedure-Process-Definition.xml
new file mode 100644
index 0000000..477a72b
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Definition.xml
@@ -0,0 +1,70 @@
+<section>
+ <title>Tasks, Procedures, and Processes defined</title>
+ <para>
+ Tasks, procedures, and processes are examples of <firstterm>user procedural guidance</firstterm> - sets of sequential instructions to be executed by an end-user to change the state of a system.
+ </para>
+
+ <formalpara>
+ <title>Tasks and Procedures</title>
+ <para>
+ The terms <firstterm>task</firstterm> and <firstterm>procedure</firstterm> are used interchangeably to refer to a set of instructions that is self-sufficient to produce a useful change in the system state. The simplest procedure / task might be: "To turn on the computer, press the power button". A more complex procedure / task might describe "how to configure a persistent firewall rule to allow access to the Tomcat server".
+ </para>
+ </formalpara>
+
+ <para>
+ The Docbook tags <literal><procedure></literal> and <literal><task></literal> are used to document procedures. The <literal><task></literal> tag is a superset of the <literal><procedure></literal> tag. As well as containing a <literal><procedure></literal>, <literal><task></literal> also contains preamble such as a task summary and task prerequisites.
+ </para>
+
+ <para>
+ Documenting procedures is described in more detail in <xref linkend="sect-writing-procedures"/>.
+ </para>
+
+ <formalpara>
+ <title>Procedural Dependencies</title>
+ <para>
+ Frequently, a procedure will rely on other procedures. For example, any procedure that involves interacting with the operating system presupposes the "Turn the computer on" procedure. In 99% of cases that particular dependency can safely be assumed implicitly, and is given here only to illustrate the principle of a <firstterm>procedural dependency</firstterm>. Procedural dependencies most obviously appear as prerequisites. In our example, you can't do anything with the operating system without first turning on the computer. "Turn on the computer" is a prerequisite for any of our hypothetical operating system tasks.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Included function pattern</title>
+ <para>
+ Procedural dependencies are dealt with using the "Included function" pattern. The Included function pattern injects a reference to a procedural dependency into the procedure with the dependency. In the case of a prerequisite, the dependency is noted in the prerequisites section, with a link to the procedure.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Complex Procedural Dependencies</title>
+ <para>
+ Procedural dependencies can be more complex. For example, consider an installation procedure that requires the user to install a package, and additionally install MySQL server, configure the MySQL root account, create a MySQL database, create a MySQL user account, set the correct permissions on the MySQL database, and edit a configuration file to provide the MySQL database name and user credentials.
+ </para>
+ </formalpara>
+
+ <para>
+ There are two patterns that can be used to document this complex scenario: the Monolithic procedure, and the Process.
+ </para>
+
+ <formalpara>
+ <title>Monolithic Procedures</title>
+ <para>
+ The first approach, that of the Monolithic procedure, is to write a single long procedure covering all of the necessary steps. The principle advantage of this approach is that the end-user can follow a single procedure to perform the entire task. The disadvantages are that although the procedure consists of several discrete tasks that represent useful state changes in their own right (and that is the way that I have described it), our monolithic procedure is not reusable for those scenarios. If we wished to provide generic guidance to "Create a MySQL database", we would have to write a separate procedure. The result is duplication of content, which is a maintenance overhead. Also, it is difficult for the user to clearly see the forest for the trees. Monolithic procedures typically have a large number of steps, and there is no clear separation of concerns. In a complex organisation different steps in the procedure may need to be carried out by different persons. Monoli
thic procedures do not map at all to these separations of concern.
+ </para>
+ </formalpara>
+
+ <para>
+ The second approach is to use an Included function pattern to document the scenario as a <firstterm>process</firstterm>.
+ </para>
+
+ <formalpara>
+ <title>Processes</title>
+ <para>
+ A process is a sequence of discrete tasks that are combined to change the state of the system in a specific way. What makes a process different from a task is that each step in a process is a useful state change in its own right (a task), whereas the steps of a task are not generally useful on their own. Using a process allows reusable procedures to be reused and single-sourced (either through transclusion when available, or by reference), or even when procedures are presented inline and duplicated in source code, a process presents a clear separation of concerns that assists the user in scoping and planning.
+ </para>
+ </formalpara>
+
+ <para>
+ Documenting processes is described in described in more detail in <xref linkend="sect-writing-processes"/>.
+ </para>
+</section>
+
+
diff --git a/en-US/sect-Task-Procedure-Process-Documenting-Procedures.xml b/en-US/sect-Task-Procedure-Process-Documenting-Procedures.xml
new file mode 100644
index 0000000..859fd6d
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Documenting-Procedures.xml
@@ -0,0 +1,16 @@
+<section id="sect-writing-procedures">
+ <title>Documenting Procedures</title>
+
+ <para>
+ Procedures provide users with a sequence of specific steps to realise a concrete outcome. End-users employ documented procedures when they are uncertain about how to obtain a specific system state. They typically search for relevant procedures based on the desired outcome.
+ </para>
+
+ <para>
+ A complete procedure provides contextual information on its use case, describes an initial state, provides a sequence of steps, optionally describes significant intermediate states, and describes a final state.
+ </para>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Task-Procedure-Process-Four-Parts-of-a-Procedure.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Task-Procedure-Process-Procedure-Writing-Guidelines.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Task-Procedure-Process-Example-Procedure.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sect-Task-Procedure-Process-Example-Procedure-Source.xml"/>
+</section>
diff --git a/en-US/sect-Task-Procedure-Process-Documenting-Processes.xml b/en-US/sect-Task-Procedure-Process-Documenting-Processes.xml
new file mode 100644
index 0000000..f3f28f6
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Documenting-Processes.xml
@@ -0,0 +1,43 @@
+<section id="sect-writing-processes">
+ <title>Documenting Processes</title>
+
+ <para>
+ Processes, also known as <firstterm>supertasks</firstterm>, are complex sequences that involve a specific combination of tasks. A process differs from a task in that each of the steps in a process is itself a useful change in the state of the system (a task in its own right), whereas the steps in a task are generally not useful in isolation.
+ </para>
+
+ <para>
+ Processes are documented using the same markup as procedures. The principle difference is that the steps in a process are usually references to other procedures, sometimes with specific modifications. For example, a step in a process might say: "Follow 'Procedure 43.2: Create a MySQL database', specifying 'testdb' as the database name".
+ </para>
+
+ <para>
+ Even when all the steps in a process are documented inline, for example as a chapter "Installing MyCustom Application", a process overview allows the user to see the overall installation process at a glance. The process overview is a high-level description of the process devoid of details (which are provided later) which acts as an aid to comprehension and planning for the end-user. It presents the "birds eye view".
+ </para>
+
+ <para>
+ For example, our custom application installation process might look like this:
+ </para>
+
+ <example>
+ <title>An Example Process</title>
+ <procedure>
+ <title>Custom Application Installation Overview</title>
+ <step><para>Install the Custom Application package</para></step>
+ <step><para>Install MySQL Server</para></step>
+ <step><para>Configure the MySQL root user account</para></step>
+ <step><para>Create the MySQL database</para></step>
+ <step><para>Create a MySQL user for the application</para></step>
+ <step><para>Edit the Custom Application configuration</para></step>
+ </procedure>
+ </example>
+
+ <para>
+ After the Installation Overview we would expect to find each step in the process documented as a separate procedure. Some of the procedures might be simply wrappers for other reused procedures, specifying custom values or giving additional guidance to used when following those procedures. Other procedures in the procedure might be unique, for example, the last one "Edit the Custom Application configuration".
+ </para>
+
+ <para>
+ Including all necessary guidance inline, without requiring the user to refer to another pdf, or jump back and forth via hyperlinks is the most user-friendly solution. In publishing systems that support transclusion of text (reuse without duplication in source code) this is possible. In publishing systems without transclusion it is a trade-off between useability and maintainability - and unmaintained docs are unusable docs.
+ </para>
+ <para>
+ Whatever the case, wherever the line is drawn between reuse and useability, as a general pattern across a large body of documentation, processes are more useable in the long run than monolithic procedures. They provide a separation of concerns for both authors and end-users: providing single points for updating procedures when a component changes, and providing separate procedures for separate pieces, which may map to different organisational roles.
+ </para>
+</section>
diff --git a/en-US/sect-Task-Procedure-Process-Example-Procedure-Source.xml b/en-US/sect-Task-Procedure-Process-Example-Procedure-Source.xml
new file mode 100644
index 0000000..ea25222
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Example-Procedure-Source.xml
@@ -0,0 +1,145 @@
+<section id="Example-Procedure-Source">
+ <title>Example Procedure Docbook source</title>
+
+ <para>
+ This is the Docbook source for <xref linkend="Example-Procedure"/>.
+ </para>
+
+<screen><![CDATA[<task>
+ <title>Add a new user with the graphical user management tools</title>
+
+ <tasksummary>
+ <para>
+ Follow this procedure to create a new user account on a Fedora system using the graphical user management tools. To create a new user with the command line tools, refer to Procedure 4.5 "Add a new user with the command line user management tools".
+ </para>
+ </tasksummary>
+
+ <taskprerequisites>
+ <title>Prerequisites</title>
+ <itemizedlist>
+ <listitem>
+ <para>Fedora installed and running</para>
+ </listitem>
+ <listitem>
+ <para>Access to the <literal>root</literal> account, or root-level privileges via <literal>sudo</literal></para>
+ </listitem>
+ </itemizedlist>
+ </taskprerequisites>
+
+ <procedure>
+
+ <step>
+ <para>
+ Ensure that the User Manager application, <literal>system-config-users</literal>, is installed.
+ </para>
+
+ <substeps>
+ <step>
+ <para>In a terminal, run the command <command>rpm -q system-config-users</command> to query the installed packages database.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ If the application is installed, the command returns the installed package version, for example:
+ </para>
+ </formalpara>
+ <screen>system-config-users-1.2.107-2.fc15.noarch</screen>
+ <para>
+ If the application is not installed, the command returns:
+ </para>
+ <screen>package system-config-users is not installed</screen>
+ </step>
+
+ <step>
+ <para>
+ If the application is not installed, run the following command with root privileges:
+ </para>
+ <screen>yum install -y system-config-users</screen>
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The <command>system-config-users</command> package is installed.
+ </para>
+ </formalpara>
+ </step>
+ </substeps>
+ </step>
+
+ <step>
+ <para>
+ Start the User Manager application from the command line or via the Graphical User Interface (GUI).
+ </para>
+
+ <substeps>
+ <step>
+ <title>Command-line option:</title>
+ <para>
+ In a terminal, run the command <command>system-config-users</command>, or <command>sudo system-config-users</command> if you have sudo privilege.
+ </para>
+
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ If the command is run with root privileges, the User Manager application appears. If the command is run with non-root privileges, a root password dialog is displayed first.
+ </para>
+ </formalpara>
+ </step>
+
+ <step>
+ <title>GUI option:</title>
+ <para>
+ In the Gnome Activities menu, type "Users" (without quotes). Select the application <literal>Users and Groups</literal>.
+ </para>
+
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ If you are logged in as root, the User Manager application appears. If you are logged with a non-root account, a root password dialog is displayed first.
+ </para>
+ </formalpara>
+ </step>
+ </substeps>
+
+ </step>
+
+ <step>
+ <para>
+ In the User Manager, click <guilabel>Add User</guilabel>.
+ </para>
+
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ The <guilabel>Add New User</guilabel> dialog appears.
+ </para>
+ </formalpara>
+ </step>
+
+ <step>
+ <para>
+ Specify the details for the new user. The following parameters are <emphasis>required</emphasis>: <literal>User Name</literal>, <literal>Password</literal>, <literal>Confirm Password</literal>. The following parameter is <emphasis>optional</emphasis>: <literal>Full Name</literal>.
+ </para>
+ <para>
+ Note that when the "Create home directory" option is selected, a home directory is created at <literal><replaceable>Home_Directory_Value</replaceable>/<replaceable>New_User_Name_Value</replaceable></literal>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Click <guilabel>OK</guilabel>.
+ </para>
+
+ <formalpara>
+ <title>Result:</title>
+ <para>
+ A new user is created, and displayed in the User Manager.
+ </para>
+ </formalpara>
+ </step>
+ </procedure>
+</task> ]]></screen>
+
+ <note>
+ <para>In Docbook 4.5 use the <literal><formalpara></literal> tag to format the step result and the procedure result. A feature request for a procedure result tag has been accepted by the Docbook TAC for inclusion in Docbook 5.1</para>
+ </note>
+
+</section>
diff --git a/en-US/sect-Task-Procedure-Process-Example-Procedure.xml b/en-US/sect-Task-Procedure-Process-Example-Procedure.xml
new file mode 100644
index 0000000..e4f8293
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Example-Procedure.xml
@@ -0,0 +1,92 @@
+<section id="Example-Procedure">
+ <title>Example Procedure</title>
+
+ <para>
+ The Docbook source for the example procedure below is included as <xref linkend="Example-Procedure-Source"/>.
+ </para>
+
+ <task>
+ <title>Add a new user with the graphical user management tools</title>
+
+ <tasksummary>
+ <para>Follow this procedure to create a new user account on a Fedora system using the graphical user management tools. To create a new user with the command line tools, refer to Procedure 4.5 "Add a new user with the command line user management tools".</para>
+ </tasksummary>
+
+ <taskprerequisites>
+ <title>Prerequisites</title>
+ <itemizedlist>
+ <listitem><para>Fedora installed and running</para></listitem>
+ <listitem><para>Access to the <literal>root</literal> account, or root-level privileges via <literal>sudo</literal></para></listitem>
+ </itemizedlist>
+ </taskprerequisites>
+ <procedure>
+ <step>
+ <para>Ensure that the User Manager application, <literal>system-config-users</literal>, is installed.</para>
+ <substeps>
+ <step>
+ <para>In a terminal, run the command <command>rpm -q system-config-users</command> to query the installed packages database.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>If the application is installed, the command returns the installed package version, for example:</para>
+ </formalpara>
+ <screen>system-config-users-1.2.107-2.fc15.noarch</screen>
+ <para>If the application is not installed, the command returns:</para>
+ <screen>package system-config-users is not installed</screen>
+ </step>
+ <step>
+ <para>If the application is not installed, run the following command with root privileges:</para>
+ <screen>yum install -y system-config-users</screen>
+ <formalpara>
+ <title>Result:</title>
+ <para>The <command>system-config-users</command> package is installed.</para>
+ </formalpara>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>Start the User Manager application from the command line or via the Graphical User Interface (GUI).</para>
+ <substeps>
+ <step>
+ <title>Command-line option:</title>
+ <para>In a terminal, run the command <command>system-config-users</command>, or <command>sudo system-config-users</command> if you have sudo privilege.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>If the command is run with root privileges, the User Manager application appears. If the command is run with non-root privileges, a root password dialog is displayed first.</para>
+ </formalpara>
+ </step>
+ <step>
+ <title>GUI option:</title>
+ <para>In the Gnome Activities menu, type "Users" (without quotes). Select the application <literal>Users and Groups</literal>.</para>
+
+ <formalpara>
+ <title>Result:</title>
+ <para>If you are logged in as root, the User Manager application appears. If you are logged with a non-root account, a root password dialog is displayed first.</para>
+ </formalpara>
+ </step>
+ </substeps>
+ </step>
+
+ <step>
+ <para>In the User Manager, click <guilabel>Add User</guilabel>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>The <guilabel>Add New User</guilabel> dialog appears.</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Specify the details for the new user. The following parameters are <emphasis>required</emphasis>: <literal>User Name</literal>, <literal>Password</literal>, <literal>Confirm Password</literal>. The following parameter is <emphasis>optional</emphasis>: <literal>Full Name</literal>.</para>
+ <para>Note that when the "Create home directory" option is selected, a home directory is created at <literal><replaceable>Home_Directory_Value</replaceable>/<replaceable>New_User_Name_Value</replaceable></literal>.</para>
+ </step>
+
+ <step>
+ <para>Click <guilabel>OK</guilabel>.</para>
+ <formalpara>
+ <title>Result:</title>
+ <para>A new user is created, and displayed in the User Manager.</para>
+ </formalpara>
+ </step>
+ </procedure>
+ </task>
+</section>
+
+
diff --git a/en-US/sect-Task-Procedure-Process-Four-Parts-of-a-Procedure.xml b/en-US/sect-Task-Procedure-Process-Four-Parts-of-a-Procedure.xml
new file mode 100644
index 0000000..d7b35a7
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Four-Parts-of-a-Procedure.xml
@@ -0,0 +1,26 @@
+<section>
+ <title>The Four Parts of a Procedure</title>
+
+ <para>Well-written procedures consist of four parts:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>1. Introduction</term>
+ <listitem><para>The Introduction, including the Procedure's title, provide the user with sufficient context to identify whether the procedure is the one that they are looking for. Many times users approach documentation with a specific problem that they need to solve, and they scan for something that matches their problem and offers a solution. The Introduction, including the title, helps readers to quickly make this determination.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>2. Prerequisites</term>
+ <listitem><para>The Prerequisites section lists the dependencies of the procedure. These are other procedures that must be performed before the steps of the procedure can be performed. For example, a configuration procedure usually requires that the product is installed. The prerequisites may be references or links to other documented procedures (for example: "Procedure 3.1: Install the product"), may be a description of the equivalent of a procedure result (for example: "A DNS entry mapping the hostname to the given IP has been created"), or may be a mixture of the two. Well-written prerequisites allow the procedure to function reliably in isolation, for example during documentation testing, or when a user jumps into the middle of a guide to solve an immediate problem.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>3. Procedure Steps</term>
+ <listitem><para>The Procedure Steps are the meat of the procedure. These are a sequential list of instructions that provide guidance to the user to perform the procedure and achieve the procedure outcome. Some of the steps may be optional, in which case the step is marked as optional, and sufficient guidance provided to enable the user to make an informed decision about the optional step. Some steps may include a "Step Result", where the outcome of a step is described to illustrate feedback on the procedure pathway.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>4. Procedure Result</term>
+ <listitem><para>The Procedure Result describes the end result state of the procedure. This is especially important for testing. Given a situation that meets the prerequisites described in the procedure prerequisites, following the procedural pathway laid out in the Procedure Steps, the end result of a well-written procedure for a tester or an end-user matches the description of the Procedure Result.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+</section>
+
diff --git a/en-US/sect-Task-Procedure-Process-Procedure-Writing-Guidelines.xml b/en-US/sect-Task-Procedure-Process-Procedure-Writing-Guidelines.xml
new file mode 100644
index 0000000..f649aae
--- /dev/null
+++ b/en-US/sect-Task-Procedure-Process-Procedure-Writing-Guidelines.xml
@@ -0,0 +1,122 @@
+<section>
+ <title>Procedure-writing Guidelines</title>
+
+ <para>
+ Well-written procedures consist of four parts:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Introduction</para>
+ </listitem>
+ <listitem>
+ <para>Prerequisites</para>
+ </listitem>
+ <listitem>
+ <para>Procedure Steps</para>
+ </listitem>
+ <listitem>
+ <para>Procedure Result</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ This section describes each of the four parts of a well-written procedure in more detail.
+ </para>
+
+ <section>
+ <title>Introduction</title>
+ <section>
+ <title>Procedure Title</title>
+ <para>
+ The procedure title is an imperative statement of the form "Do Something". As a user scans documentation for a solution they are often thinking "I want to...". A well-written procedure title matches that question, to allow the user to quickly locate it.
+ </para>
+
+ <para>
+ Badly-written documentation does not use a standard pattern for procedure titles. Employing standard design patterns allows users to quickly learn the design patterns that have been used for the documentation, and then use those patterns to quickly assess the relevance of documentation without needing to read deeply in to the content.
+ </para>
+ <para>
+ The following procedure titles employ a pattern that is better suited to a conceptual overview. Remember that users searching for procedural guidance usually approach the documentation with the question "I want to...". The example procedure titles below do not directly answer this question.
+ </para>
+ <example>
+ <title>Examples of badly-written procedure titles</title>
+ <itemizedlist>
+ <listitem><para>Fedora CD-ROM Install</para></listitem>
+ <listitem><para>Mounting an NFS share</para></listitem>
+ <listitem><para>Live USB key creation</para></listitem>
+ </itemizedlist>
+ </example>
+ <para>
+ Well-written procedure titles follow the design pattern: Complete the question "I want to...". The example procedure titles below follow this pattern, and allow users scanning search results or a table of contents to quickly identify it as procedural guidance, and to assess its relevance to their situation.
+ </para>
+ <example>
+ <title>Examples of well-written procedure titles</title>
+ <itemizedlist>
+ <listitem><para>Install Fedora from CD-ROM</para></listitem>
+ <listitem><para>Mount an NFS share</para></listitem>
+ <listitem><para>Create a bootable live USB key</para></listitem>
+ </itemizedlist>
+ </example>
+ </section>
+
+ <section>
+ <title>Introductory Paragraph</title>
+ <para>The Introductory Paragraph provides additional context. When a reader locates a likely candidate procedure through search or browsing a table of contents, the Introductory Paragraph provides them with additional detail beyond the title. This additional detail may include further elaboration of the result produced by the procedure, a description of circumstances in which the procedure is appropriate, and links to other related procedures. After reading a well-written Introductory Paragraph a user is certain about whether or not this is the applicable procedure. In some cases the Introductory Paragraph may provide sufficient information to redirect the user to another similar but subtly different procedure which is a better match for their situation.
+ </para>
+ <para>
+ The standard design pattern for the Introductory Paragraph is the following:
+ </para>
+ <para>
+ "Follow this procedure to <replaceable>obtain specific outcome</replaceable>. To <replaceable>something similar but different</replaceable> refer to <replaceable>Other procedure</replaceable>.
+ </para>
+ <para>
+ When procedures are authored as modular, reusable topics, rather than inline as static narrative, related and similar procedures are specified using the topic metadata, rather than written inline. The topic assembly system generates disambiguation references automatically.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ The Prerequisites portion of a procedure presents the necessary preconditions for successful execution of the procedure. These preconditions must be satisfied before the procedure is started. A well-written procedure is sufficiently explicit in its dependencies that it can be executed or tested in isolation from the rest of the surrounding documentation. In the case of execution, users will frequently jump into documentation from a search or from a table of contents, attempting to solve an immediate problem. Well-written procedures do not assume that readers have read through and followed previous sections of the documentation. Procedures are tested as discrete, isolated units during Documentation QA in order to ensure this atomicity.
+ </para>
+ </section>
+
+ <section>
+ <title>Procedure Steps</title>
+
+ <para>
+ Procedure steps are written using the <firstterm>imperative mood</firstterm>. This is the grammatical form used to give commands: "Do this...", "Press this key...", "Enter the following information...".
+ </para>
+
+ <para>
+ The goal of user documentation is to reduce uncertainty. Once the user is certain that the they have the right procedure, each step then guides them through a pathway with the greatest amount of certainty as possible. Procedural steps do not attempt to educate the user on background conceptual information, but provide a set of concise steps to achieve a desired outcome.
+ </para>
+
+ <para>
+ In a case where a procedure involves options, each option is presented with sufficient information for the user to make an informed decision. Remember that the goal of documentation is to reduce uncertainty. Presenting users with options devoid of sufficient context for them to choose increases their uncertainty.
+ </para>
+
+ <para>
+ If the amount of contextual information required to make a decision in a procedure begins to overload the procedure with conceptual background, break it out of the procedure, and consider providing different procedures for each of the use cases, or breaking the procedure into a shared preliminary procedure with separate subsequent procedures for the different options.
+ </para>
+ </section>
+ <section>
+ <title>Step Results</title>
+ <para>
+ Some procedure steps present a step result. A step result helps the user to verify that they have executed the step correctly and the system is responding in the manner predicted by the procedure writer. Without step results a user may not notice a deviation from the documented procedural pathway, due to either user error or an unexpected response by the system, until they have travelled several steps beyond the point of departure.
+ </para>
+
+ <para>
+ Procedure step results are presented in the <firstterm>simple present tense</firstterm>. This is the grammatical form used to describe something concrete and immediately present: "The window appears...", "A new user is created...", "The command returns the following result...". Complex tenses, future tenses, and wording that is hypothetical or "hopeful" ("it will do this", "you should see this") inject uncertainty. Remember - the goal of documentation is to reduce uncertainty. Documentation that speaks with certainty creates certainty. Clear, confident step results mean that the user is certain they are on the right track as they follow the procedure, and when the user experiences a result contrary to the documented one, they are just as certain that things have gone awry.
+ </para>
+ </section>
+
+ <section>
+ <title>Procedure Result</title>
+
+ <para>
+ The Procedure Result describes the end state of the system when the steps of the procedure have been performed correctly. This is a complete description of the procedure results, the goal of which is to leave no uncertainty about the extent and limit of the procedure's outcome.
+ </para>
+
+ </section>
+</section>
More information about the docs-commits
mailing list