3.7. Pre-release software and draft documentation

Completed documentation for pre-release software is not the same thing as draft documentation.

Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.

In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.

3.7.1. Denoting pre-release software

Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.

To create that mark do the following:

Add the software's pre-release version number, or equivalent state information, to the subtitle in your Book_Info.xml file. Place this additional text in <remark> tags. For example:
```
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
```
add show_remarks to the publican.cfg file and set it to '1':
```
show_remarks: 1
```

When you build your book with this <remark> tag and the show_remarks setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html.

Because this approach makes no changes to the information in Book_Info.xml used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.

Important

It is the writer's responsibility to remove the <remark> tag and its contents and remove or turn off show_remarks when documentation is updated for use with the release version of the software.

3.7.2. Denoting draft documentation

Unfinished documentation made available to others for review should be labeled clearly as such.

To add the draft watermark to your documentation add the status="draft" attribute to the <article>, <book> or <set> tag in your document's root node. For example:
```
<book status="draft">
```

By default, your root node is the <book> tag in your Doc_Name.xml file.

If you are working on an article or set, the root node is the <article> or <set> tag in Doc_Name.xml.

Adding the status="draft" attribute causes each page of the document to show the draft watermark. This is by design.

Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.

3.7.3. Denoting draft documentation of pre-release software

To denote unfinished documentation of pre-release software properly, do both previously noted procedures.