8:08 p.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
In my recent blog post[0] I laid out a proposal for implementing Docs QA in a way that
will both help make sure that our guides and articles are correct and consistant and will
help get our new contributors on their way to contributing words to our guides.
The blog post was a proposal and was a derivative of various talks made with Fedora
contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately, closed
due to the lack of Docs contributors at SELF which is why I'm taking the time to bring
this proposal to the Fedora Docs community now for discussion.
I encourage everyone to reply with comments, questions, and perhaps a proposal of their
own.
[0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
- --Eric "Sparks"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
=8SBU
-----END PGP SIGNATURE-----
6:43 a.m.
On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
In my recent blog post[0] I laid out a proposal for implementing Docs QA in a way that
will both help make sure that our guides and articles are correct and consistant and will
help get our new contributors on their way to contributing words to our guides.
The blog post was a proposal and was a derivative of various talks made with Fedora
contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately, closed
due to the lack of Docs contributors at SELF which is why I'm taking the time to bring
this proposal to the Fedora Docs community now for discussion.
I encourage everyone to reply with comments, questions, and perhaps a proposal of their
own.
A few thoughts on this:
A Q.A. layer is a really good idea. It's always hard to check your own work.
I think for it work well it will need a formal test plan, with a
description of how to "test" a document.
Content and encoding are two separate concerns.
Content means documented instructions on using a product, such as
installation and configuration procedures. Those things can be tested in
isolation, if there is a good specification for things like a
pre-requisites section for procedures.
Encoding means the Docbook tags used to mark up the content. Testing
content and testing encoding are two distinct, but overlapping skillsets.
I'd say that these things are needed to do this:
1. Docbook tag style guide
2. Procedure format specification
3. Documentation Test plan
So authors use the Docbook tag style guide and Procedure format
specification to author, and then testers can follow the Test plan to
check the docs against that.
Content testers check the built output against the format specification,
and also test the procedure to make sure that the documented steps
produce the documented result.
Encoding testers check the source against the tag style guide.
Both could be done by the same person, but they should be done as two
separate passes. They are different, but related concerns.
[0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
- --Eric "Sparks"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
=8SBU
-----END PGP SIGNATURE-----
6:20 p.m.
The Fedora Documentation Guide looks like the right place to put these
kinds of things (procedure specification / documentation testing plan).
I'd be happy to draft some content for that. Sound like a good idea?
Another good source of material for that guide might be the JBoss
Documentation Guide:
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
- Josh
On 06/13/2011 09:43 PM, Joshua Wulf wrote:
On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> In my recent blog post[0] I laid out a proposal for implementing Docs QA in a way
that will both help make sure that our guides and articles are correct and consistant and
will help get our new contributors on their way to contributing words to our guides.
>
> The blog post was a proposal and was a derivative of various talks made with Fedora
contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately, closed
due to the lack of Docs contributors at SELF which is why I'm taking the time to bring
this proposal to the Fedora Docs community now for discussion.
>
> I encourage everyone to reply with comments, questions, and perhaps a proposal of
their own.
A few thoughts on this:
A Q.A. layer is a really good idea. It's always hard to check your own work.
I think for it work well it will need a formal test plan, with a
description of how to "test" a document.
Content and encoding are two separate concerns.
Content means documented instructions on using a product, such as
installation and configuration procedures. Those things can be tested in
isolation, if there is a good specification for things like a
pre-requisites section for procedures.
Encoding means the Docbook tags used to mark up the content. Testing
content and testing encoding are two distinct, but overlapping skillsets.
I'd say that these things are needed to do this:
1. Docbook tag style guide
2. Procedure format specification
3. Documentation Test plan
So authors use the Docbook tag style guide and Procedure format
specification to author, and then testers can follow the Test plan to
check the docs against that.
Content testers check the built output against the format specification,
and also test the procedure to make sure that the documented steps
produce the documented result.
Encoding testers check the source against the tag style guide.
Both could be done by the same person, but they should be done as two
separate passes. They are different, but related concerns.
>
>
> [0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>
> - --Eric "Sparks"
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
>
> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
> =8SBU
> -----END PGP SIGNATURE-----
10:21 p.m.
I've got a bit of time to kill at the moment, so I've written up a draft
chapter on writing procedures.
Any feedback on it appreciated.
I haven't included a description of the xml tags used to mark up
procedures yet because I'm not sure if we've standardized on <procedure>
or <task> for this.
Once that's clear I can write it up, along with a draft Documentation
Test Pattern for testing procedures.
- Josh
On 06/14/2011 09:20 AM, Joshua Wulf wrote:
The Fedora Documentation Guide looks like the right place to put
these
kinds of things (procedure specification / documentation testing plan).
I'd be happy to draft some content for that. Sound like a good idea?
Another good source of material for that guide might be the JBoss
Documentation Guide:
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
- Josh
On 06/13/2011 09:43 PM, Joshua Wulf wrote:
> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA256
>>
>> In my recent blog post[0] I laid out a proposal for implementing Docs QA in a way
that will both help make sure that our guides and articles are correct and consistant and
will help get our new contributors on their way to contributing words to our guides.
>>
>> The blog post was a proposal and was a derivative of various talks made with
Fedora contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately,
closed due to the lack of Docs contributors at SELF which is why I'm taking the time
to bring this proposal to the Fedora Docs community now for discussion.
>>
>> I encourage everyone to reply with comments, questions, and perhaps a proposal of
their own.
>
> A few thoughts on this:
>
> A Q.A. layer is a really good idea. It's always hard to check your own work.
>
> I think for it work well it will need a formal test plan, with a
> description of how to "test" a document.
>
> Content and encoding are two separate concerns.
>
> Content means documented instructions on using a product, such as
> installation and configuration procedures. Those things can be tested in
> isolation, if there is a good specification for things like a
> pre-requisites section for procedures.
>
>
> Encoding means the Docbook tags used to mark up the content. Testing
> content and testing encoding are two distinct, but overlapping skillsets.
>
> I'd say that these things are needed to do this:
>
> 1. Docbook tag style guide
> 2. Procedure format specification
> 3. Documentation Test plan
>
> So authors use the Docbook tag style guide and Procedure format
> specification to author, and then testers can follow the Test plan to
> check the docs against that.
>
> Content testers check the built output against the format specification,
> and also test the procedure to make sure that the documented steps
> produce the documented result.
>
> Encoding testers check the source against the tag style guide.
>
> Both could be done by the same person, but they should be done as two
> separate passes. They are different, but related concerns.
>
>>
>>
>> [0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>
>> - --Eric "Sparks"
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.11 (GNU/Linux)
>>
>> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>> =8SBU
>> -----END PGP SIGNATURE-----
>
>
4:06 a.m.
I added processes and definitions for task, procedure, and process.
Is there a better way for me to do this than attaching xml to an email?
On 06/14/2011 01:21 PM, Joshua Wulf wrote:
I've got a bit of time to kill at the moment, so I've written
up a draft
chapter on writing procedures.
Any feedback on it appreciated.
I haven't included a description of the xml tags used to mark up
procedures yet because I'm not sure if we've standardized on <procedure>
or <task> for this.
Once that's clear I can write it up, along with a draft Documentation
Test Pattern for testing procedures.
- Josh
On 06/14/2011 09:20 AM, Joshua Wulf wrote:
> The Fedora Documentation Guide looks like the right place to put these
> kinds of things (procedure specification / documentation testing plan).
>
> I'd be happy to draft some content for that. Sound like a good idea?
>
> Another good source of material for that guide might be the JBoss
> Documentation Guide:
>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>
> - Josh
>
>
> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA256
>>>
>>> In my recent blog post[0] I laid out a proposal for implementing Docs QA in a
way that will both help make sure that our guides and articles are correct and consistant
and will help get our new contributors on their way to contributing words to our guides.
>>>
>>> The blog post was a proposal and was a derivative of various talks made with
Fedora contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately,
closed due to the lack of Docs contributors at SELF which is why I'm taking the time
to bring this proposal to the Fedora Docs community now for discussion.
>>>
>>> I encourage everyone to reply with comments, questions, and perhaps a
proposal of their own.
>>
>> A few thoughts on this:
>>
>> A Q.A. layer is a really good idea. It's always hard to check your own work.
>>
>> I think for it work well it will need a formal test plan, with a
>> description of how to "test" a document.
>>
>> Content and encoding are two separate concerns.
>>
>> Content means documented instructions on using a product, such as
>> installation and configuration procedures. Those things can be tested in
>> isolation, if there is a good specification for things like a
>> pre-requisites section for procedures.
>>
>>
>> Encoding means the Docbook tags used to mark up the content. Testing
>> content and testing encoding are two distinct, but overlapping skillsets.
>>
>> I'd say that these things are needed to do this:
>>
>> 1. Docbook tag style guide
>> 2. Procedure format specification
>> 3. Documentation Test plan
>>
>> So authors use the Docbook tag style guide and Procedure format
>> specification to author, and then testers can follow the Test plan to
>> check the docs against that.
>>
>> Content testers check the built output against the format specification,
>> and also test the procedure to make sure that the documented steps
>> produce the documented result.
>>
>> Encoding testers check the source against the tag style guide.
>>
>> Both could be done by the same person, but they should be done as two
>> separate passes. They are different, but related concerns.
>>
>>>
>>>
>>> [0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>
>>> - --Eric "Sparks"
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
>>> -----BEGIN PGP SIGNATURE-----
>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>
>>> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>> =8SBU
>>> -----END PGP SIGNATURE-----
>>
>>
>
>
5:56 a.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Josh,
I'll respond to ALL of your message at once. :)
I think your assessment of QA is spot on. There are two separate "functions"
that someone doing QA would need to cover. I also believe the Documentation Guide[0] is
the perfect place to document this. I'm not sure if this is where you put your
chapter but if not please feel free to add it.
[0] git://fedorahosted.org/git/docs/documentation-guide.git
- --Eric
On Tue, Jun 14, 2011 at 01:21:16PM +1000, Joshua Wulf wrote:
I've got a bit of time to kill at the moment, so I've written
up a draft
chapter on writing procedures.
Any feedback on it appreciated.
I haven't included a description of the xml tags used to mark up
procedures yet because I'm not sure if we've standardized on <procedure>
or <task> for this.
Once that's clear I can write it up, along with a draft Documentation
Test Pattern for testing procedures.
- Josh
On 06/14/2011 09:20 AM, Joshua Wulf wrote:
> The Fedora Documentation Guide looks like the right place to put these
> kinds of things (procedure specification / documentation testing plan).
>
> I'd be happy to draft some content for that. Sound like a good idea?
>
> Another good source of material for that guide might be the JBoss
> Documentation Guide:
>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>
> - Josh
>
>
> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA256
>>>
>>> In my recent blog post[0] I laid out a proposal for implementing Docs QA in
a way that will both help make sure that our guides and articles are correct and
consistant and will help get our new contributors on their way to contributing words to
our guides.
>>>
>>> The blog post was a proposal and was a derivative of various talks made with
Fedora contributors at SouthEast LinuxFest (SELF). The discussions were, unfortunately,
closed due to the lack of Docs contributors at SELF which is why I'm taking the time
to bring this proposal to the Fedora Docs community now for discussion.
>>>
>>> I encourage everyone to reply with comments, questions, and perhaps a
proposal of their own.
>>
>> A few thoughts on this:
>>
>> A Q.A. layer is a really good idea. It's always hard to check your own
work.
>>
>> I think for it work well it will need a formal test plan, with a
>> description of how to "test" a document.
>>
>> Content and encoding are two separate concerns.
>>
>> Content means documented instructions on using a product, such as
>> installation and configuration procedures. Those things can be tested in
>> isolation, if there is a good specification for things like a
>> pre-requisites section for procedures.
>>
>>
>> Encoding means the Docbook tags used to mark up the content. Testing
>> content and testing encoding are two distinct, but overlapping skillsets.
>>
>> I'd say that these things are needed to do this:
>>
>> 1. Docbook tag style guide
>> 2. Procedure format specification
>> 3. Documentation Test plan
>>
>> So authors use the Docbook tag style guide and Procedure format
>> specification to author, and then testers can follow the Test plan to
>> check the docs against that.
>>
>> Content testers check the built output against the format specification,
>> and also test the procedure to make sure that the documented steps
>> produce the documented result.
>>
>> Encoding testers check the source against the tag style guide.
>>
>> Both could be done by the same person, but they should be done as two
>> separate passes. They are different, but related concerns.
>>
>>>
>>>
>>> [0] http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>
>>> - --Eric "Sparks"
>>> -----BEGIN PGP SIGNATURE-----
>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>
>>> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>> =8SBU
>>> -----END PGP SIGNATURE-----
>>
>>
>
>
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
<chapter>
<title>Writing 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>
<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, should help 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 should be 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 for a tester or an end-user should
match the description of the Procedure Result.</para></listitem>
</varlistentry>
</variablelist>
</section>
<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>
<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
procedural 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>
<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>
<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>
<title>Example Procedure</title>
<example>
<title>An Example Procedure</title>
<procedure>
<title>Add a new user with the graphical user management
tools</title>
<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>
<formalpara>
<title>Prerequisites</title>
<para>
<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>
</para>
</formalpara>
<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>: User Name, Password, Confirm Password. The
following parameter is <emphasis>optional</emphasis>: Full Name.</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>
</example>
</section>
</chapter>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk33PnMACgkQU03aaJDMNEUdnwD9HD86Jna709zzRqRLS9OgT8lY
yfE35+fhomFpMHlj834A/0drHmgraYahr8SLTjhQcqn7ULq8QmXsi/hjJvpKKyQo
=1JgV
-----END PGP SIGNATURE-----
7:13 a.m.
Cool, thanks. I'll check it in tomorrow.
- Josh
~ Kirtan is Life! ~
Sent from my iPhone.
On 14/06/2011, at 8:56 PM, "Eric H. Christensen"
<sparks(a)fedoraproject.org> wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Josh,
I'll respond to ALL of your message at once. :)
I think your assessment of QA is spot on. There are two separate "functions"
that someone doing QA would need to cover. I also believe the Documentation Guide[0] is
the perfect place to document this. I'm not sure if this is where you put your
chapter but if not please feel free to add it.
[0] git://fedorahosted.org/git/docs/documentation-guide.git
- --Eric
On Tue, Jun 14, 2011 at 01:21:16PM +1000, Joshua Wulf wrote:
> I've got a bit of time to kill at the moment, so I've written up a draft
> chapter on writing procedures.
>
> Any feedback on it appreciated.
>
> I haven't included a description of the xml tags used to mark up
> procedures yet because I'm not sure if we've standardized on
<procedure>
> or <task> for this.
>
> Once that's clear I can write it up, along with a draft Documentation
> Test Pattern for testing procedures.
>
> - Josh
>
> On 06/14/2011 09:20 AM, Joshua Wulf wrote:
>> The Fedora Documentation Guide looks like the right place to put these
>> kinds of things (procedure specification / documentation testing plan).
>>
>> I'd be happy to draft some content for that. Sound like a good idea?
>>
>> Another good source of material for that guide might be the JBoss
>> Documentation Guide:
>>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>>
>> - Josh
>>
>>
>> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>> Hash: SHA256
>>>>
>>>> In my recent blog post[0] I laid out a proposal for implementing Docs QA
in a way that will both help make sure that our guides and articles are correct and
consistant and will help get our new contributors on their way to contributing words to
our guides.
>>>>
>>>> The blog post was a proposal and was a derivative of various talks made
with Fedora contributors at SouthEast LinuxFest (SELF). The discussions were,
unfortunately, closed due to the lack of Docs contributors at SELF which is why I'm
taking the time to bring this proposal to the Fedora Docs community now for discussion.
>>>>
>>>> I encourage everyone to reply with comments, questions, and perhaps a
proposal of their own.
>>>
>>> A few thoughts on this:
>>>
>>> A Q.A. layer is a really good idea. It's always hard to check your own
work.
>>>
>>> I think for it work well it will need a formal test plan, with a
>>> description of how to "test" a document.
>>>
>>> Content and encoding are two separate concerns.
>>>
>>> Content means documented instructions on using a product, such as
>>> installation and configuration procedures. Those things can be tested in
>>> isolation, if there is a good specification for things like a
>>> pre-requisites section for procedures.
>>>
>>>
>>> Encoding means the Docbook tags used to mark up the content. Testing
>>> content and testing encoding are two distinct, but overlapping skillsets.
>>>
>>> I'd say that these things are needed to do this:
>>>
>>> 1. Docbook tag style guide
>>> 2. Procedure format specification
>>> 3. Documentation Test plan
>>>
>>> So authors use the Docbook tag style guide and Procedure format
>>> specification to author, and then testers can follow the Test plan to
>>> check the docs against that.
>>>
>>> Content testers check the built output against the format specification,
>>> and also test the procedure to make sure that the documented steps
>>> produce the documented result.
>>>
>>> Encoding testers check the source against the tag style guide.
>>>
>>> Both could be done by the same person, but they should be done as two
>>> separate passes. They are different, but related concerns.
>>>
>>>>
>>>>
>>>> [0]
http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>>
>>>> - --Eric "Sparks"
>>>> -----BEGIN PGP SIGNATURE-----
>>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>>
>>>> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>>> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>>> =8SBU
>>>> -----END PGP SIGNATURE-----
>>>
>>>
>>
>>
>
>
> --
> Give us your feedback on JBoss Enterprise Documentation, take the key
> survey:
> http://www.keysurvey.com/survey/361436/1065/
>
>
>
> <chapter>
> <title>Writing 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>
>
> <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, should help
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 should be 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 for a tester or an end-user should
match the description of the Procedure Result.</para></listitem>
> </varlistentry>
> </variablelist>
> </section>
>
> <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>
>
> <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
procedural 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>
> <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>
>
> <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>
> <title>Example Procedure</title>
> <example>
> <title>An Example Procedure</title>
> <procedure>
> <title>Add a new user with the graphical user management
tools</title>
>
> <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>
>
> <formalpara>
> <title>Prerequisites</title>
> <para>
> <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>
> </para>
> </formalpara>
>
> <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>: User Name, Password, Confirm
Password. The following parameter is <emphasis>optional</emphasis>: Full
Name.</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>
> </example>
> </section>
> </chapter>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk33PnMACgkQU03aaJDMNEUdnwD9HD86Jna709zzRqRLS9OgT8lY
yfE35+fhomFpMHlj834A/0drHmgraYahr8SLTjhQcqn7ULq8QmXsi/hjJvpKKyQo
=1JgV
-----END PGP SIGNATURE-----
6:20 p.m.
OK, I... think I committed it. I'm not sure, I've never used git before.
Can you let me know if it's committed ok please.
- Josh
On 06/14/2011 10:13 PM, Joshua Wulf wrote:
Cool, thanks. I'll check it in tomorrow.
- Josh
~ Kirtan is Life! ~
Sent from my iPhone.
On 14/06/2011, at 8:56 PM, "Eric H. Christensen"
<sparks(a)fedoraproject.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> Josh,
>
> I'll respond to ALL of your message at once. :)
>
> I think your assessment of QA is spot on. There are two separate
"functions" that someone doing QA would need to cover. I also believe the
Documentation Guide[0] is the perfect place to document this. I'm not sure if this is
where you put your chapter but if not please feel free to add it.
>
> [0] git://fedorahosted.org/git/docs/documentation-guide.git
>
> - --Eric
>
> On Tue, Jun 14, 2011 at 01:21:16PM +1000, Joshua Wulf wrote:
>> I've got a bit of time to kill at the moment, so I've written up a draft
>> chapter on writing procedures.
>>
>> Any feedback on it appreciated.
>>
>> I haven't included a description of the xml tags used to mark up
>> procedures yet because I'm not sure if we've standardized on
<procedure>
>> or <task> for this.
>>
>> Once that's clear I can write it up, along with a draft Documentation
>> Test Pattern for testing procedures.
>>
>> - Josh
>>
>> On 06/14/2011 09:20 AM, Joshua Wulf wrote:
>>> The Fedora Documentation Guide looks like the right place to put these
>>> kinds of things (procedure specification / documentation testing plan).
>>>
>>> I'd be happy to draft some content for that. Sound like a good idea?
>>>
>>> Another good source of material for that guide might be the JBoss
>>> Documentation Guide:
>>>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>>>
>>> - Josh
>>>
>>>
>>> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>>>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>>> Hash: SHA256
>>>>>
>>>>> In my recent blog post[0] I laid out a proposal for implementing Docs
QA in a way that will both help make sure that our guides and articles are correct and
consistant and will help get our new contributors on their way to contributing words to
our guides.
>>>>>
>>>>> The blog post was a proposal and was a derivative of various talks
made with Fedora contributors at SouthEast LinuxFest (SELF). The discussions were,
unfortunately, closed due to the lack of Docs contributors at SELF which is why I'm
taking the time to bring this proposal to the Fedora Docs community now for discussion.
>>>>>
>>>>> I encourage everyone to reply with comments, questions, and perhaps a
proposal of their own.
>>>>
>>>> A few thoughts on this:
>>>>
>>>> A Q.A. layer is a really good idea. It's always hard to check your
own work.
>>>>
>>>> I think for it work well it will need a formal test plan, with a
>>>> description of how to "test" a document.
>>>>
>>>> Content and encoding are two separate concerns.
>>>>
>>>> Content means documented instructions on using a product, such as
>>>> installation and configuration procedures. Those things can be tested in
>>>> isolation, if there is a good specification for things like a
>>>> pre-requisites section for procedures.
>>>>
>>>>
>>>> Encoding means the Docbook tags used to mark up the content. Testing
>>>> content and testing encoding are two distinct, but overlapping
skillsets.
>>>>
>>>> I'd say that these things are needed to do this:
>>>>
>>>> 1. Docbook tag style guide
>>>> 2. Procedure format specification
>>>> 3. Documentation Test plan
>>>>
>>>> So authors use the Docbook tag style guide and Procedure format
>>>> specification to author, and then testers can follow the Test plan to
>>>> check the docs against that.
>>>>
>>>> Content testers check the built output against the format specification,
>>>> and also test the procedure to make sure that the documented steps
>>>> produce the documented result.
>>>>
>>>> Encoding testers check the source against the tag style guide.
>>>>
>>>> Both could be done by the same person, but they should be done as two
>>>> separate passes. They are different, but related concerns.
>>>>
>>>>>
>>>>>
>>>>> [0]
http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>>>
>>>>> - --Eric "Sparks"
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
>>>>> -----BEGIN PGP SIGNATURE-----
>>>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>>>
>>>>> iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>>>> 26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>>>> =8SBU
>>>>> -----END PGP SIGNATURE-----
>>>>
>>>>
>>>
>>>
>>
>>
>> --
>> Give us your feedback on JBoss Enterprise Documentation, take the key
>> survey:
>> http://www.keysurvey.com/survey/361436/1065/
>>
>
>>
>>
>> <chapter>
>> <title>Writing 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>
>>
>> <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, should help
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 should be 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 for a tester or an
end-user should match the description of the Procedure
Result.</para></listitem>
>> </varlistentry>
>> </variablelist>
>> </section>
>>
>> <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>
>>
>> <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
procedural 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>
>> <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>
>>
>> <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>
>> <title>Example Procedure</title>
>> <example>
>> <title>An Example Procedure</title>
>> <procedure>
>> <title>Add a new user with the graphical user management
tools</title>
>>
>> <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>
>>
>> <formalpara>
>> <title>Prerequisites</title>
>> <para>
>> <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>
>> </para>
>> </formalpara>
>>
>> <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>: User Name, Password, Confirm
Password. The following parameter is <emphasis>optional</emphasis>: Full
Name.</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>
>> </example>
>> </section>
>> </chapter>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
>
> iF4EAREIAAYFAk33PnMACgkQU03aaJDMNEUdnwD9HD86Jna709zzRqRLS9OgT8lY
> yfE35+fhomFpMHlj834A/0drHmgraYahr8SLTjhQcqn7ULq8QmXsi/hjJvpKKyQo
> =1JgV
> -----END PGP SIGNATURE-----
7:27 p.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
I'm not seeing any new changes to the repo.
Did you:
git add <file>
git commit -m "<message explaining commit>"
git push
?
- --Eric
On Wed, Jun 15, 2011 at 09:20:36AM +1000, Joshua Wulf wrote:
OK, I... think I committed it. I'm not sure, I've never used
git before.
Can you let me know if it's committed ok please.
- Josh
On 06/14/2011 10:13 PM, Joshua Wulf wrote:
> Cool, thanks. I'll check it in tomorrow.
>
> - Josh
>
> ~ Kirtan is Life! ~
> Sent from my iPhone.
>
> On 14/06/2011, at 8:56 PM, "Eric H. Christensen"
<sparks(a)fedoraproject.org> wrote:
>
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA256
>>
>> Josh,
>>
>> I'll respond to ALL of your message at once. :)
>>
>> I think your assessment of QA is spot on. There are two separate
"functions" that someone doing QA would need to cover. I also believe the
Documentation Guide[0] is the perfect place to document this. I'm not sure if this is
where you put your chapter but if not please feel free to add it.
>>
>> [0] git://fedorahosted.org/git/docs/documentation-guide.git
>>
>> - --Eric
>>
>> On Tue, Jun 14, 2011 at 01:21:16PM +1000, Joshua Wulf wrote:
>>> I've got a bit of time to kill at the moment, so I've written up a
draft
>>> chapter on writing procedures.
>>>
>>> Any feedback on it appreciated.
>>>
>>> I haven't included a description of the xml tags used to mark up
>>> procedures yet because I'm not sure if we've standardized on
<procedure>
>>> or <task> for this.
>>>
>>> Once that's clear I can write it up, along with a draft Documentation
>>> Test Pattern for testing procedures.
>>>
>>> - Josh
>>>
>>> On 06/14/2011 09:20 AM, Joshua Wulf wrote:
>>>> The Fedora Documentation Guide looks like the right place to put these
>>>> kinds of things (procedure specification / documentation testing plan).
>>>>
>>>> I'd be happy to draft some content for that. Sound like a good
idea?
>>>>
>>>> Another good source of material for that guide might be the JBoss
>>>> Documentation Guide:
>>>>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>>>>
>>>> - Josh
>>>>
>>>>
>>>> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>>>>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>>>> Hash: SHA256
>>>>>>
>>>>>> In my recent blog post[0] I laid out a proposal for implementing
Docs QA in a way that will both help make sure that our guides and articles are correct
and consistant and will help get our new contributors on their way to contributing words
to our guides.
>>>>>>
>>>>>> The blog post was a proposal and was a derivative of various
talks made with Fedora contributors at SouthEast LinuxFest (SELF). The discussions were,
unfortunately, closed due to the lack of Docs contributors at SELF which is why I'm
taking the time to bring this proposal to the Fedora Docs community now for discussion.
>>>>>>
>>>>>> I encourage everyone to reply with comments, questions, and
perhaps a proposal of their own.
>>>>>
>>>>> A few thoughts on this:
>>>>>
>>>>> A Q.A. layer is a really good idea. It's always hard to check
your own work.
>>>>>
>>>>> I think for it work well it will need a formal test plan, with a
>>>>> description of how to "test" a document.
>>>>>
>>>>> Content and encoding are two separate concerns.
>>>>>
>>>>> Content means documented instructions on using a product, such as
>>>>> installation and configuration procedures. Those things can be
tested in
>>>>> isolation, if there is a good specification for things like a
>>>>> pre-requisites section for procedures.
>>>>>
>>>>>
>>>>> Encoding means the Docbook tags used to mark up the content.
Testing
>>>>> content and testing encoding are two distinct, but overlapping
skillsets.
>>>>>
>>>>> I'd say that these things are needed to do this:
>>>>>
>>>>> 1. Docbook tag style guide
>>>>> 2. Procedure format specification
>>>>> 3. Documentation Test plan
>>>>>
>>>>> So authors use the Docbook tag style guide and Procedure format
>>>>> specification to author, and then testers can follow the Test plan
to
>>>>> check the docs against that.
>>>>>
>>>>> Content testers check the built output against the format
specification,
>>>>> and also test the procedure to make sure that the documented steps
>>>>> produce the documented result.
>>>>>
>>>>> Encoding testers check the source against the tag style guide.
>>>>>
>>>>> Both could be done by the same person, but they should be done as
two
>>>>> separate passes. They are different, but related concerns.
>>>>>
>>>>>>
>>>>>>
>>>>>> [0]
http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>>>>
>>>>>> - --Eric "Sparks"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk33/FoACgkQU03aaJDMNEUE0wD+JhYgsWiCwpIgNTXLv4g2OCtf
o6nOfkFPSjP79rtb0N0BAJLRzEuPo6YrSfWIwdq7sz5NbNuTM6CuEmIXJIX7nx+9
=TZpK
-----END PGP SIGNATURE-----
>>>>>> -----BEGIN PGP SIGNATURE-----
>>>>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>>>>
>>>>>>
iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>>>>>
26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>>>>> =8SBU
>>>>>> -----END PGP SIGNATURE-----
>>>>>
>>>>>
>>>>
>>>>
>>>
>>>
>>> --
>>> Give us your feedback on JBoss Enterprise Documentation, take the key
>>> survey:
>>> http://www.keysurvey.com/survey/361436/1065/
>>>
>>
>>>
>>>
>>> <chapter>
>>> <title>Writing 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>
>>>
>>> <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, should help
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 should be 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 for a tester or an
end-user should match the description of the Procedure
Result.</para></listitem>
>>> </varlistentry>
>>> </variablelist>
>>> </section>
>>>
>>> <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>
>>>
>>> <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 procedural 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>
>>> <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>
>>>
>>> <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>
>>> <title>Example Procedure</title>
>>> <example>
>>> <title>An Example Procedure</title>
>>> <procedure>
>>> <title>Add a new user with the graphical user management
tools</title>
>>>
>>> <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>
>>>
>>> <formalpara>
>>> <title>Prerequisites</title>
>>> <para>
>>> <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>
>>> </para>
>>> </formalpara>
>>>
>>> <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>: User Name, Password,
Confirm Password. The following parameter is <emphasis>optional</emphasis>:
Full Name.</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>
>>> </example>
>>> </section>
>>> </chapter>
>>
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.11 (GNU/Linux)
>>
>> iF4EAREIAAYFAk33PnMACgkQU03aaJDMNEUdnwD9HD86Jna709zzRqRLS9OgT8lY
>> yfE35+fhomFpMHlj834A/0drHmgraYahr8SLTjhQcqn7ULq8QmXsi/hjJvpKKyQo
>> =1JgV
>> -----END PGP SIGNATURE-----
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
8:16 p.m.
[jwulf@gaura documentation-guide]$ git push
fatal: The remote end hung up unexpectedly
[jwulf@gaura documentation-guide]$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 4 commits.
Do I need some sshkey magic for this?
On 06/15/2011 10:27 AM, Eric H. Christensen wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
I'm not seeing any new changes to the repo.
Did you:
git add <file>
git commit -m "<message explaining commit>"
git push
?
- --Eric
On Wed, Jun 15, 2011 at 09:20:36AM +1000, Joshua Wulf wrote:
> OK, I... think I committed it. I'm not sure, I've never used git before.
> Can you let me know if it's committed ok please.
>
> - Josh
>
> On 06/14/2011 10:13 PM, Joshua Wulf wrote:
>> Cool, thanks. I'll check it in tomorrow.
>>
>> - Josh
>>
>> ~ Kirtan is Life! ~
>> Sent from my iPhone.
>>
>> On 14/06/2011, at 8:56 PM, "Eric H. Christensen"
<sparks(a)fedoraproject.org> wrote:
>>
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA256
>>>
>>> Josh,
>>>
>>> I'll respond to ALL of your message at once. :)
>>>
>>> I think your assessment of QA is spot on. There are two separate
"functions" that someone doing QA would need to cover. I also believe the
Documentation Guide[0] is the perfect place to document this. I'm not sure if this is
where you put your chapter but if not please feel free to add it.
>>>
>>> [0] git://fedorahosted.org/git/docs/documentation-guide.git
>>>
>>> - --Eric
>>>
>>> On Tue, Jun 14, 2011 at 01:21:16PM +1000, Joshua Wulf wrote:
>>>> I've got a bit of time to kill at the moment, so I've written up
a draft
>>>> chapter on writing procedures.
>>>>
>>>> Any feedback on it appreciated.
>>>>
>>>> I haven't included a description of the xml tags used to mark up
>>>> procedures yet because I'm not sure if we've standardized on
<procedure>
>>>> or <task> for this.
>>>>
>>>> Once that's clear I can write it up, along with a draft
Documentation
>>>> Test Pattern for testing procedures.
>>>>
>>>> - Josh
>>>>
>>>> On 06/14/2011 09:20 AM, Joshua Wulf wrote:
>>>>> The Fedora Documentation Guide looks like the right place to put
these
>>>>> kinds of things (procedure specification / documentation testing
plan).
>>>>>
>>>>> I'd be happy to draft some content for that. Sound like a good
idea?
>>>>>
>>>>> Another good source of material for that guide might be the JBoss
>>>>> Documentation Guide:
>>>>>
https://hudson.jboss.org/jenkins/job/JBoss_Documentation_Guide/lastSucces...
>>>>>
>>>>> - Josh
>>>>>
>>>>>
>>>>> On 06/13/2011 09:43 PM, Joshua Wulf wrote:
>>>>>> On 06/11/2011 11:08 AM, Eric H. Christensen wrote:
>>>>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>>>>> Hash: SHA256
>>>>>>>
>>>>>>> In my recent blog post[0] I laid out a proposal for
implementing Docs QA in a way that will both help make sure that our guides and articles
are correct and consistant and will help get our new contributors on their way to
contributing words to our guides.
>>>>>>>
>>>>>>> The blog post was a proposal and was a derivative of various
talks made with Fedora contributors at SouthEast LinuxFest (SELF). The discussions were,
unfortunately, closed due to the lack of Docs contributors at SELF which is why I'm
taking the time to bring this proposal to the Fedora Docs community now for discussion.
>>>>>>>
>>>>>>> I encourage everyone to reply with comments, questions, and
perhaps a proposal of their own.
>>>>>>
>>>>>> A few thoughts on this:
>>>>>>
>>>>>> A Q.A. layer is a really good idea. It's always hard to check
your own work.
>>>>>>
>>>>>> I think for it work well it will need a formal test plan, with a
>>>>>> description of how to "test" a document.
>>>>>>
>>>>>> Content and encoding are two separate concerns.
>>>>>>
>>>>>> Content means documented instructions on using a product, such
as
>>>>>> installation and configuration procedures. Those things can be
tested in
>>>>>> isolation, if there is a good specification for things like a
>>>>>> pre-requisites section for procedures.
>>>>>>
>>>>>>
>>>>>> Encoding means the Docbook tags used to mark up the content.
Testing
>>>>>> content and testing encoding are two distinct, but overlapping
skillsets.
>>>>>>
>>>>>> I'd say that these things are needed to do this:
>>>>>>
>>>>>> 1. Docbook tag style guide
>>>>>> 2. Procedure format specification
>>>>>> 3. Documentation Test plan
>>>>>>
>>>>>> So authors use the Docbook tag style guide and Procedure format
>>>>>> specification to author, and then testers can follow the Test
plan to
>>>>>> check the docs against that.
>>>>>>
>>>>>> Content testers check the built output against the format
specification,
>>>>>> and also test the procedure to make sure that the documented
steps
>>>>>> produce the documented result.
>>>>>>
>>>>>> Encoding testers check the source against the tag style guide.
>>>>>>
>>>>>> Both could be done by the same person, but they should be done as
two
>>>>>> separate passes. They are different, but related concerns.
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> [0]
http://fedora-sparks.blogspot.com/2011/06/fedora-docs-qa-process.html
>>>>>>>
>>>>>>> - --Eric "Sparks"
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
>>>>>>> -----BEGIN PGP SIGNATURE-----
>>>>>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>>>>>
>>>>>>>
iF4EAREIAAYFAk3ywAoACgkQU03aaJDMNEUBlQD/cj+quMZ4414HKI4+0lGsvatL
>>>>>>>
26F7RY2zkLInoi04Qh0BAJzIhEmaQHNnS7PXlrAOnIx+xOnPa7td1qfwmLjOWgxx
>>>>>>> =8SBU
>>>>>>> -----END PGP SIGNATURE-----
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> Give us your feedback on JBoss Enterprise Documentation, take the key
>>>> survey:
>>>> http://www.keysurvey.com/survey/361436/1065/
>>>>
>>>
>>>>
>>>>
>>>> <chapter>
>>>> <title>Writing 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>
>>>>
>>>> <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, should help
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 should be 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 for a tester or an
end-user should match the description of the Procedure
Result.</para></listitem>
>>>> </varlistentry>
>>>> </variablelist>
>>>> </section>
>>>>
>>>> <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>
>>>>
>>>> <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 procedural 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>
>>>> <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>
>>>>
>>>> <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>
>>>> <title>Example Procedure</title>
>>>> <example>
>>>> <title>An Example Procedure</title>
>>>> <procedure>
>>>> <title>Add a new user with the graphical user management
tools</title>
>>>>
>>>> <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>
>>>>
>>>> <formalpara>
>>>> <title>Prerequisites</title>
>>>> <para>
>>>> <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>
>>>> </para>
>>>> </formalpara>
>>>>
>>>> <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>: User Name, Password,
Confirm Password. The following parameter is <emphasis>optional</emphasis>:
Full Name.</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>
>>>> </example>
>>>> </section>
>>>> </chapter>
>>>
>>> -----BEGIN PGP SIGNATURE-----
>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>
>>> iF4EAREIAAYFAk33PnMACgkQU03aaJDMNEUdnwD9HD86Jna709zzRqRLS9OgT8lY
>>> yfE35+fhomFpMHlj834A/0drHmgraYahr8SLTjhQcqn7ULq8QmXsi/hjJvpKKyQo
>>> =1JgV
>>> -----END PGP SIGNATURE-----
>
>
> --
> Give us your feedback on JBoss Enterprise Documentation, take the key
> survey:
> http://www.keysurvey.com/survey/361436/1065/
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk33/FoACgkQU03aaJDMNEUE0wD+JhYgsWiCwpIgNTXLv4g2OCtf
o6nOfkFPSjP79rtb0N0BAJLRzEuPo6YrSfWIwdq7sz5NbNuTM6CuEmIXJIX7nx+9
=TZpK
-----END PGP SIGNATURE-----
2:57 a.m.
OK, I checked it out with:
git clone git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
When I try to push it back, I get the following error, which suggests to
me that I don't have the right permissions?
[jwulf@gaura en-US]$ git push
Counting objects: 17, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (13/13), done.
Writing objects: 100% (13/13), 12.50 KiB, done.
Total 13 (delta 3), reused 0 (delta 0)
error: insufficient permission for adding an object to repository
database ./objects
fatal: failed to write object
error: unpack failed: unpack-objects abnormal exit
To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
! [remote rejected] master -> master (n/a (unpacker error))
error: failed to push some refs to
'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
5:28 a.m.
Looks like I'm not in the docs-writer group at the moment, just the
publican svn commit group.
Can I be added to the docs-writer group please.
- Josh
On 06/15/2011 05:57 PM, Joshua Wulf wrote:
OK, I checked it out with:
git clone git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
When I try to push it back, I get the following error, which suggests to
me that I don't have the right permissions?
[jwulf@gaura en-US]$ git push
Counting objects: 17, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (13/13), done.
Writing objects: 100% (13/13), 12.50 KiB, done.
Total 13 (delta 3), reused 0 (delta 0)
error: insufficient permission for adding an object to repository
database ./objects
fatal: failed to write object
error: unpack failed: unpack-objects abnormal exit
To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
! [remote rejected] master -> master (n/a (unpacker error))
error: failed to push some refs to
'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
5:53 a.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Well, since you asked so nicely...
I've added and sponsored you in the Docs and Docs-Writers groups so that should be
squared away now.
- --Eric
On Wed, Jun 15, 2011 at 08:28:21PM +1000, Joshua Wulf wrote:
Looks like I'm not in the docs-writer group at the moment, just
the
publican svn commit group.
Can I be added to the docs-writer group please.
- Josh
On 06/15/2011 05:57 PM, Joshua Wulf wrote:
> OK, I checked it out with:
> git clone git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>
> When I try to push it back, I get the following error, which suggests to
> me that I don't have the right permissions?
>
>
> [jwulf@gaura en-US]$ git push
> Counting objects: 17, done.
> Delta compression using up to 2 threads.
> Compressing objects: 100% (13/13), done.
> Writing objects: 100% (13/13), 12.50 KiB, done.
> Total 13 (delta 3), reused 0 (delta 0)
> error: insufficient permission for adding an object to repository
> database ./objects
>
> fatal: failed to write object
> error: unpack failed: unpack-objects abnormal exit
> To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
> ! [remote rejected] master -> master (n/a (unpacker error))
> error: failed to push some refs to
> 'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk34jyUACgkQU03aaJDMNEVf6AD+MZP/ppuNbWW+v94RSld0Rpyd
BC2ZGYvc79yVclBp52AA/RkUyYYxapfkpGxeovyRjrxBDPX9SnC1Wv0gqR3XeqON
=sThA
-----END PGP SIGNATURE-----
6:02 a.m.
It looks like Erics up early today, I saw the email and was going to
get it when I got to work, but when I logged in it was already done.
On Wed, Jun 15, 2011 at 6:53 AM, Eric H. Christensen
<sparks(a)fedoraproject.org> wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Well, since you asked so nicely...
I've added and sponsored you in the Docs and Docs-Writers groups so that should be
squared away now.
- --Eric
On Wed, Jun 15, 2011 at 08:28:21PM +1000, Joshua Wulf wrote:
> Looks like I'm not in the docs-writer group at the moment, just the
> publican svn commit group.
>
> Can I be added to the docs-writer group please.
>
> - Josh
>
>
> On 06/15/2011 05:57 PM, Joshua Wulf wrote:
> > OK, I checked it out with:
> > git clone git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
> >
> > When I try to push it back, I get the following error, which suggests to
> > me that I don't have the right permissions?
> >
> >
> > [jwulf@gaura en-US]$ git push
> > Counting objects: 17, done.
> > Delta compression using up to 2 threads.
> > Compressing objects: 100% (13/13), done.
> > Writing objects: 100% (13/13), 12.50 KiB, done.
> > Total 13 (delta 3), reused 0 (delta 0)
> > error: insufficient permission for adding an object to repository
> > database ./objects
> >
> > fatal: failed to write object
> > error: unpack failed: unpack-objects abnormal exit
> > To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
> > ! [remote rejected] master -> master (n/a (unpacker error))
> > error: failed to push some refs to
> > 'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
>
>
> --
> Give us your feedback on JBoss Enterprise Documentation, take the key
> survey:
> http://www.keysurvey.com/survey/361436/1065/
>
--
Zach Oglesby
oglesbyzm(a)gmail.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iF4EAREIAAYFAk34jyUACgkQU03aaJDMNEVf6AD+MZP/ppuNbWW+v94RSld0Rpyd
BC2ZGYvc79yVclBp52AA/RkUyYYxapfkpGxeovyRjrxBDPX9SnC1Wv0gqR3XeqON
=sThA
-----END PGP SIGNATURE-----
--
docs mailing list
docs(a)lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
7:02 a.m.
Thanks guys!
[jwulf@gaura documentation-guide]$ git push
Counting objects: 17, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (13/13), done.
Writing objects: 100% (13/13), 12.50 KiB, done.
Total 13 (delta 3), reused 0 (delta 0)
To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
539837c..ecc0d70 master -> master
On 06/15/2011 09:02 PM, Zach Oglesby wrote:
It looks like Erics up early today, I saw the email and was going to
get it when I got to work, but when I logged in it was already done.
On Wed, Jun 15, 2011 at 6:53 AM, Eric H. Christensen
<sparks(a)fedoraproject.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> Well, since you asked so nicely...
>
> I've added and sponsored you in the Docs and Docs-Writers groups so that should
be squared away now.
>
> - --Eric
>
> On Wed, Jun 15, 2011 at 08:28:21PM +1000, Joshua Wulf wrote:
>> Looks like I'm not in the docs-writer group at the moment, just the
>> publican svn commit group.
>>
>> Can I be added to the docs-writer group please.
>>
>> - Josh
>>
>>
>> On 06/15/2011 05:57 PM, Joshua Wulf wrote:
>>> OK, I checked it out with:
>>> git clone git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>>
>>> When I try to push it back, I get the following error, which suggests to
>>> me that I don't have the right permissions?
>>>
>>>
>>> [jwulf@gaura en-US]$ git push
>>> Counting objects: 17, done.
>>> Delta compression using up to 2 threads.
>>> Compressing objects: 100% (13/13), done.
>>> Writing objects: 100% (13/13), 12.50 KiB, done.
>>> Total 13 (delta 3), reused 0 (delta 0)
>>> error: insufficient permission for adding an object to repository
>>> database ./objects
>>>
>>> fatal: failed to write object
>>> error: unpack failed: unpack-objects abnormal exit
>>> To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>> ! [remote rejected] master -> master (n/a (unpacker error))
>>> error: failed to push some refs to
>>> 'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
>>
>>
>> --
>> Give us your feedback on JBoss Enterprise Documentation, take the key
>> survey:
>> http://www.keysurvey.com/survey/361436/1065/
>>
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
>
> iF4EAREIAAYFAk34jyUACgkQU03aaJDMNEVf6AD+MZP/ppuNbWW+v94RSld0Rpyd
> BC2ZGYvc79yVclBp52AA/RkUyYYxapfkpGxeovyRjrxBDPX9SnC1Wv0gqR3XeqON
> =sThA
> -----END PGP SIGNATURE-----
> --
> docs mailing list
> docs(a)lists.fedoraproject.org
> To unsubscribe:
> https://admin.fedoraproject.org/mailman/listinfo/docs
>
7:54 a.m.
Josh,
Saw you pushed and then removed what you were working on. Feel free
to keep the not-so-ready stuff in the repo as the entire guide is very
far away from prime time.
--Eric
On Wed, Jun 15, 2011 at 08:02, Joshua Wulf <jwulf(a)redhat.com> wrote:
Thanks guys!
[jwulf@gaura documentation-guide]$ git push
Counting objects: 17, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (13/13), done.
Writing objects: 100% (13/13), 12.50 KiB, done.
Total 13 (delta 3), reused 0 (delta 0)
To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
539837c..ecc0d70 master -> master
On 06/15/2011 09:02 PM, Zach Oglesby wrote:
> It looks like Erics up early today, I saw the email and was going to
> get it when I got to work, but when I logged in it was already done.
>
> On Wed, Jun 15, 2011 at 6:53 AM, Eric H. Christensen
> <sparks(a)fedoraproject.org> wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA256
>>
>> Well, since you asked so nicely...
>>
>> I've added and sponsored you in the Docs and Docs-Writers groups so that
should be squared away now.
>>
>> - --Eric
>>
>> On Wed, Jun 15, 2011 at 08:28:21PM +1000, Joshua Wulf wrote:
>>> Looks like I'm not in the docs-writer group at the moment, just the
>>> publican svn commit group.
>>>
>>> Can I be added to the docs-writer group please.
>>>
>>> - Josh
>>>
>>>
>>> On 06/15/2011 05:57 PM, Joshua Wulf wrote:
>>>> OK, I checked it out with:
>>>> git clone
git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>>>
>>>> When I try to push it back, I get the following error, which suggests to
>>>> me that I don't have the right permissions?
>>>>
>>>>
>>>> [jwulf@gaura en-US]$ git push
>>>> Counting objects: 17, done.
>>>> Delta compression using up to 2 threads.
>>>> Compressing objects: 100% (13/13), done.
>>>> Writing objects: 100% (13/13), 12.50 KiB, done.
>>>> Total 13 (delta 3), reused 0 (delta 0)
>>>> error: insufficient permission for adding an object to repository
>>>> database ./objects
>>>>
>>>> fatal: failed to write object
>>>> error: unpack failed: unpack-objects abnormal exit
>>>> To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>>> ! [remote rejected] master -> master (n/a (unpacker error))
>>>> error: failed to push some refs to
>>>>
'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
>>>
>>>
>>> --
>>> Give us your feedback on JBoss Enterprise Documentation, take the key
>>> survey:
>>> http://www.keysurvey.com/survey/361436/1065/
>>>
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.11 (GNU/Linux)
>>
>> iF4EAREIAAYFAk34jyUACgkQU03aaJDMNEVf6AD+MZP/ppuNbWW+v94RSld0Rpyd
>> BC2ZGYvc79yVclBp52AA/RkUyYYxapfkpGxeovyRjrxBDPX9SnC1Wv0gqR3XeqON
>> =sThA
>> -----END PGP SIGNATURE-----
>> --
>> docs mailing list
>> docs(a)lists.fedoraproject.org
>> To unsubscribe:
>> https://admin.fedoraproject.org/mailman/listinfo/docs
>>
>
>
>
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
--
docs mailing list
docs(a)lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
8:08 a.m.
I should have just removed one chapter I was working on, "Problem and
Solution spaces", which was breaking the build. The "Tasks, Procedures,
and Processes" chapter should still be there... I hope!
Is there any way I can trigger a rebuild of the doc on the stage to see?
On 06/15/2011 10:54 PM, Eric "Sparks" Christensen wrote:
Josh,
Saw you pushed and then removed what you were working on. Feel free
to keep the not-so-ready stuff in the repo as the entire guide is very
far away from prime time.
--Eric
On Wed, Jun 15, 2011 at 08:02, Joshua Wulf <jwulf(a)redhat.com> wrote:
> Thanks guys!
>
> [jwulf@gaura documentation-guide]$ git push
> Counting objects: 17, done.
> Delta compression using up to 2 threads.
> Compressing objects: 100% (13/13), done.
> Writing objects: 100% (13/13), 12.50 KiB, done.
> Total 13 (delta 3), reused 0 (delta 0)
> To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
> 539837c..ecc0d70 master -> master
>
>
> On 06/15/2011 09:02 PM, Zach Oglesby wrote:
>> It looks like Erics up early today, I saw the email and was going to
>> get it when I got to work, but when I logged in it was already done.
>>
>> On Wed, Jun 15, 2011 at 6:53 AM, Eric H. Christensen
>> <sparks(a)fedoraproject.org> wrote:
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA256
>>>
>>> Well, since you asked so nicely...
>>>
>>> I've added and sponsored you in the Docs and Docs-Writers groups so that
should be squared away now.
>>>
>>> - --Eric
>>>
>>> On Wed, Jun 15, 2011 at 08:28:21PM +1000, Joshua Wulf wrote:
>>>> Looks like I'm not in the docs-writer group at the moment, just the
>>>> publican svn commit group.
>>>>
>>>> Can I be added to the docs-writer group please.
>>>>
>>>> - Josh
>>>>
>>>>
>>>> On 06/15/2011 05:57 PM, Joshua Wulf wrote:
>>>>> OK, I checked it out with:
>>>>> git clone
git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>>>>
>>>>> When I try to push it back, I get the following error, which suggests
to
>>>>> me that I don't have the right permissions?
>>>>>
>>>>>
>>>>> [jwulf@gaura en-US]$ git push
>>>>> Counting objects: 17, done.
>>>>> Delta compression using up to 2 threads.
>>>>> Compressing objects: 100% (13/13), done.
>>>>> Writing objects: 100% (13/13), 12.50 KiB, done.
>>>>> Total 13 (delta 3), reused 0 (delta 0)
>>>>> error: insufficient permission for adding an object to repository
>>>>> database ./objects
>>>>>
>>>>> fatal: failed to write object
>>>>> error: unpack failed: unpack-objects abnormal exit
>>>>> To git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git
>>>>> ! [remote rejected] master -> master (n/a (unpacker error))
>>>>> error: failed to push some refs to
>>>>>
'git+ssh://jwulf@fedorahosted.org/git/docs/documentation-guide.git'
>>>>
>>>>
>>>> --
>>>> Give us your feedback on JBoss Enterprise Documentation, take the key
>>>> survey:
>>>> http://www.keysurvey.com/survey/361436/1065/
>>>>
--
Give us your feedback on JBoss Enterprise Documentation, take the key
survey:
http://www.keysurvey.com/survey/361436/1065/
>>> -----BEGIN PGP SIGNATURE-----
>>> Version: GnuPG v1.4.11 (GNU/Linux)
>>>
>>> iF4EAREIAAYFAk34jyUACgkQU03aaJDMNEVf6AD+MZP/ppuNbWW+v94RSld0Rpyd
>>> BC2ZGYvc79yVclBp52AA/RkUyYYxapfkpGxeovyRjrxBDPX9SnC1Wv0gqR3XeqON
>>> =sThA
>>> -----END PGP SIGNATURE-----
>>> --
>>> docs mailing list
>>> docs(a)lists.fedoraproject.org
>>> To unsubscribe:
>>> https://admin.fedoraproject.org/mailman/listinfo/docs
>>>
>>
>>
>>
>
>
> --
> Give us your feedback on JBoss Enterprise Documentation, take the key
> survey:
> http://www.keysurvey.com/survey/361436/1065/
>
> --
> docs mailing list
> docs(a)lists.fedoraproject.org
> To unsubscribe:
> https://admin.fedoraproject.org/mailman/listinfo/docs
>
4698
days inactive
4702
days old
16 comments
4 participants
participants (4)
-
Eric Christensen -
Eric Christensen -
Joshua Wulf -
Zach Oglesby