openstack-doc-core team mailing list archive

[David Cramer <david.cramer@xxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

That would be a <procedure> in DocBook. In DocBook the <title> for a
<procedure> is optional, but we could change that. Often you'll see a
convention where the titles of procedures have to follow a grammatical
pattern (e.g. they have to start with an infinitive "To start the
server"). An advantage of procedures is that if you xref to a <step>
in a procedure, it will automatically add the word "step" plus the
number to the link text.

David

On 03/30/2012 02:49 PM, Lorin Hochstein wrote:
> Hi doc'ers:
> 
> Many of the documented tasks require a sequence of steps, i.e.
> 
> First, do this… Next, do that… Afterwards, do blah, etc….
> 
> Can we come up with a convention for how to document this?
> Personally, I like explicitly numbering the steps rather than using
> "first", "second" in prose form.
> 
> 1. Do this
> 
> 2. Do that
> 
> 3. Do the other thing
> 
> I don't have a specific proposal about the Docbook markup tags to
> use. if I was doing it in Markdown, I would do something like:
> 
> ### 1. Foo
> 
> You do "foo" by typing the following command
> 
> ### 2. Bar
> 
> You do "bar" by typing the following command
> 
> 
> 
> Take care,
> 
> Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis
> Services, Inc. www.nimbisservices.com
> <https://www.nimbisservices.com/>
> 
> 
> 
> 
> 
> 
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJPdjVBAAoJEMHeSXG7afUhaL8H/2fyr8NJbWT+xPUolFq1YYIF
wDVnxM2bKD8L2B+CtyDVu03HvNTptc5qSRZKeB7W5CRBF3McUyVtUKDC2aH93rlk
429w6EicRmumYIDqIiMchBaHSfpgif0obhUuNP1md9jy5kN7tvo3QUUjJgPv0SF/
u6UODP0kTJNbv68MwJz87MMlsaYeElNWqPHdLPLT0zzHsSH3vdDZBgnNIK2+jxuK
EfiMos+OweTJV1prxMvUMp7/nO6iWrSMxuAij8tTFjT8DtkQcRTsX5p3J4+Vc6pP
+hPVxbmjBJAtt2lapdyzHxr5KIjjJEieopXQSNIreIN7FDeBywxx3jJhtbbdIDU=
=/9wK
-----END PGP SIGNATURE-----