Writing for DocBook using the wiki

Writing documentation using the Wiki

This page describes specific issues with using the Wiki to write tutorials and chapters for larger works that are intended for publication, such as Fedora Documentation . This page is likely to grow and change, as original ideas are replaced with new ones.

See the page on WikiEditing for information on how to start writing on this Wiki. Technical content markup is covered in WikiEditing#Marking_Technical_Terms.

The main purpose of these additional guidelines is to help ensure that it easy for your draft documents to be converted into DocBook, the XML file format used for master copies of Fedora documentation.

Wiki Markup May Be Different Here
Because of issues we discover about how the Wiki converts to XML, we are constantly updating accepted markup practices for areas of the Wiki such as Docs/Beats and Docs/Drafts . In general, we try to push the changes into WikiEditing (in particular, WikiEditing#Marking_Technical_Terms ). Sometimes we need to create an exception to a rule. This usually occurs when the Wiki markup choice is for style purposes, but it makes very ugly XML.

Here is an overview of how to work with a draft document:

Golden Rule

Treat other people's documents as you would have them treat your own.

Just like with CVS access, anyone in the DocWritersGroup has full access to edit anything in the Docs/Drafts tree. If you are going to do anything major to another writer's document, check with him/her first.

Create Each Page with the Full Name

The MoinMoin Wiki treats the path as part of the name of each page. This means that you must start a new page by creating a link with the full path:

[[/Docs/Drafts/MyNewPage| Long name of page]] 

This creates the page /Docs/Drafts/MyNewPage. This is a different page to /MyNewPage, and MoinMoin does not relate the two in any way.

For the same reason, you must always use the full name of your page when creating links to it from elsewhere in this Wiki.

To create draft documentation for the Documentation Project, create the link on the drafts page .

If you wish to use this Wiki to draft documentation for general release, e-mail the Documentation Project mailing list to be added to the DocsWritersGroup.

Use One Wiki Page per Chapter or Tutorial

Each Wiki page will become a single XML file when exported to DocBook. Our DocBook usage is this:

• One book = one parent file that calls in all prefaces, chapters, and appendixes
• One chapter = one file
• One section = one <section> within a file
• One article/tutorial = one file containing one or more sections

To follow this example in the Wiki:

• One book = one parent Wiki page that is a Table of Contents of all the chapter pages
• One chapter = one Wiki page, with one or more sections
• One section = one part of a Wiki page marked by the = = , == ==, etc. around the title
• One article/tutorial = one Wiki page containing one or more sections.

For example:

• Docs/Drafts/SELinuxHowTo -- the book has a ToC
• Docs/Drafts/SELinuxHowTo/WritingPolicy -- a chapter within the book

Start the Main Page of the Document with a Summary Block

The summary block provides basic information about the document to readers and potential contributors. The summary remains constant even as the contents of the document change. Filling in the summary block also helps you, by clarifying the scope and purpose of your document.

Summary Blocks are for draft purposes only.
The Summary Block is removed from final documents. It exists on draft documents to assist authors and reviewers working with incomplete documents.

Select the Show Raw Text option from the More Actions drop-down list on the sidebar, and copy all of the text between the START and END lines to the top of your document.

Fill in the summary block with the details of your document. See the summary blocks of existing draft documentation for examples.

START OF SUMMARY

THIS IS A DRAFT ONLY, FOR USE BY DOCUMENTATION WRITERS AND EDITORS.
DO NOT RELY ON IT FOR ANY ADVICE UNTIL THIS NOTICE DISAPPEARS AND THE DOCUMENT IS PUBLISHED AS FINAL.

Documentation Summary:

Purpose:

Audience:

Assumptions:

Related Documents:

Lead Writer:

---

END OF SUMMARY

Here are explanations of each section:

Purpose: A brief summary of what the document explains or describes.

Audience: The people that you expect will benefit from reading the document. Describe their circumstances, rather than attempting to categorise them. "Users who wish to run a Web server on their Fedora system" is a good audience description, "administrators" or "developers" are too vague.

Assumptions: Specify the initial conditions of the system, and any prerequisites for the reader. You should always assume a default Fedora installation (specify the relevent installation types - Desktop, Workstation, Server), and describe how to install any additional software required in the document itself. The other important assumption to specify is the state of the account that the reader has on the system - in most cases the correct assumption is that the reader has an account with the default settings. Always specify if the reader requires the root password for the system.

Related Documents: Other documents on this Wiki or published on the Web that you think are relevent to your document. In particular, list related Fedora Documentation Project and Linux Documentation Project documents that you are aware of. This section helps to minimise duplication of effort, as well as providing a useful set of references.

Lead Writer: Your Wiki UserName. Any writer can make small amendments to the document, but large changes should always be discussed with the lead writer.

All of the summary items will change and grow as the document develops - you should fill in each item as best you can initially, and amend them whenever you think it necessary.

Remember to Subscribe to Your Page !

Subscribe to your page, to ensure that you receive an e-mail each time that any other person updates your page.

To subscribe to a page, click the Subscribe link on the sidebar.

Use Sections

Sections, like this one, and sub-sections, are easy to convert to sections in DocBook. Use them freely. For larger documents, create a page under the main page for each chapter or section.

The top heading for the document uses one set of equal signs. Each section heading uses two sets of equal signs. Heading for any subsections use three sets of equal signs.

= Document Heading =
== Section Heading ==
=== Subsection Heading ===

Empty sections should be avoided.

All Links Must be Complete URLs

Normal Wiki pages convert WikiNames into valid links. Once a Wiki page has been exported to DocBook these links become invalid. For this reason, write all links to other pages and websites in your documents as external links - with a complete URL on a separate line from the main text.

For example, write links to the ["FAQ"] on this Wiki as:

• http://www.fedoraproject.org/wiki/FAQ

Follow the Style Guidelines

The Fedora Documentation Guide provides a chapter on good writing style:

• DocsProject/StyleGuide

These guidelines not only benefit your readers directly, but they also assist collaborators, editors, and the translators that convert the original documents into other languages.

Exceptions to Wiki Markup Rules

• Do not indent admonitions
• Do not indent code blocks
• Do not indent tables (admonitions)

Further Information

• HelpForBeginners introduces the concepts of Wiki
• HelpOnEditing describes the markup used by MoinMoin
• Fundamentals of technical documentation in the Fedora Documentation Guide
• Composition tips in the Fedora Documentation Guide
• Fedora Documentation Project