Fedora-Specific Conventions
The Fedora Project uses specific conventions that extend beyond the general style rules and guidelines. These conventions exist to produce specific results from the toolchains or to better address the specific requirements of the Fedora Project.
Screenshots and Images
Images and especially screenshots are hard to maintain, hard to translate, and have to be changed constantly with every test.
Screenshots do not give any more information than is already given with the text. The user is most often following along with the instructions, so the screen is up in front of them already.
Many people perceive that screenshots are necessary in help documents, often because they've seen other documents use screenshots. Avoid this trap. Screenshots lower the quality of the document by taking up valuable space with repetitive imagery and distracting authors from maintaining the far more valuable content.
Diagrams are different from screenshots. A diagram is a graphic that is self-descriptive and in many cases can be very useful or show things that cannot be described as well with words. In such cases it is worth the extra effort to maintain the graphic, including dealing with localization. Fortunately, most documents do not need more than one or two diagrams.
General Conventions
Software Management
Software that appears in any official Fedora documentation must adhere to these guidelines:
- Software must be available in the official Fedora software repositories for the release of Fedora to which the documentation applies.
- Software installation must be done via Fedora software management tools, preferably
yum. If you document using GUI tools for package installation and management, cover the default application (pirut) before others, and cover it consistently. - Software must not require user compilation from source, or rebuilding from source RPMs.
- Guides must not encourage reconfiguration of file system resources, security contexts, or any other resources from a software package that conflict with the intention of the maintainer for that software package.
Administration Tools
Guides must use the following conventions for system administration:
- Neither assume, nor configure,
sudorights. Use the following command instead:
su -c "<COMMAND>"
- To configure the current or persistent activation of services through initscripts, use the
/sbin/chkconfigand/sbin/servicebinaries.
DocBook XML
The preferred format for long-term maintenance of documents is DocBook XML. This format stores contextual style information without concern for document rendering and avoids common limitations of other document storage formats.
DocBook XML conventions are documented in the Fedora Project Documentation Guide:
http://docs.fedoraproject.org/documentation-guide/
Wiki
Wiki markup is a structured form of plain text that is not as complex as DocBook XML and has become a popular format for new writing. The wiki format and the limited available markup are simple. Wiki is easy to read and edit in normal plain text editors. Unfortunately, it lacks the contextual markup that DocBook XML provides. The Fedora Project has adopted specific conventions to provide basic contextual support in the wiki format.
ReST
ReST is a lightweight structure form of plain text that can be used to produce meaningful XML output.
Plain Text
Plain text documents contain no markup for style or context. They also lack any inherent structure. Original writing in plain text generally requires revision, including the addition of markup, before publication. A plain text document that uses wiki conventions and markup is easier to translate into wiki format, and using those conventions can improve the readability and structure of the document.
Other Formats
There are many other formats for text storage. Each may provide different features and drawbacks. If a specific structure is adhered to, the amount of effort required to convert documents between different formats can be minimized.