XHTML
Check out my writing samples for the fictional company, RTFM-Industries. They’re meant to be generic, since I don’t own the docs I’ve written at former companies. The intent here is to demonstrate my approach to writing docs with a little bit of flair.
Documentation dashboards overview
<body>
<h1>RTFM-Industries Documentation Dashboards</h1>
<p>
RTFM-Industries Documentation Dashboards provide technical writers with visualized data to track documentation requests.
Each dashboard tracks the following metrics:
</p>
<ul>
<li>Requests for new feature documentation</li>
<li>Request for documentation bug fixes</li>
<li>Percentage of documentation completed per project</li>
</ul>
<figure>
<img
src=" ../images/best-practice-documentation-dashboards.png "
alt="image of RTFM-Industries Documentation Dashboards "
/>
<figcaption>RTFM-Industries Documentation Dashboards</figcaption>
</figure>
<p>
Within each dashboard, a tech writer can learn more about each data point by clicking on it. Requests are color-coded to signify priority:
</p>
<ul>
<li>
<span class="red-txt">Red</span> = you forgot to write the documentation and everyone knows it
</li>
<li>
<span class="yellow-txt">Yellow</span> = you've successfully pushed the deadline back by pretending to be sick
</li>
<li>
<span class="green-txt">Green</span> = you've got PLENTY of time to write the docs (as long as nothing goes wrong)
</li>
</ul>
<p>
To adjust these priorities, see the <a href="adjust-doc-priority.htm">Adjusting Documentation Priorities</a> section.
</p>
<h2>Export Documentation Dashboards</h2>
<p>
RTFM-Industries Dashboard tiles can be exported into the following file type: (Excel, PDF, RTF, CSV).
</p>
<p>
<div class="note">
<span class="bold">Note:</span>
All RTFM-Industries Documentation Dashboards are fully HTML5 and do not require Microsoft Silverlight.
</div>
</p>
<h2>Prerequisites & licensing</h2>
<ul>
<li>SaaS client</li>
<li>
<a href="request-RTFM-Industries-dashboards.htm">
Request the RTFM-Industries Documentation Dashboard feature
</a>
</li>
<li>
User assigned the Tech Writer
<a href="../sys-admin/roles/tech-writer-power-user">power user role</a>
</li>
</ul>
<h2>Navigation path</h2>
<p>Home > Dashboards</p>
<h2>Next steps</h2>
<p>
<a href="create-doc-dashboard.htm">Create a new Documentation Dashboard</a>
</p>
</body>Create a new documentation dashboard
<body>
<h1>Create a new documentation dashboard</h1>
<p>
The creation of a custom Documentation Dashboard helps to visualize the
effectiveness of published documentation based on topic type (concept, task,
reference).
</p>
<h2>Prerequisites</h2>
<ul>
<li>Dashboard Designer role</li>
<li><a href="doc-dashboards-setup">Documentation Dashboards setup</a></li>
</ul>
<h2>Navigation path</h2>
<p>Home > Dashboards > Create New</p>
<h2>Task</h2>
<ol>
<li>Click <span class="bold">Add Report</span>.</li>
<li>
From the Report Type dropdown, select a topic type and enable the chekbox
next to each documentation file you want to evaluate.
</li>
<li>Specify a report code, name, and description.</li>
<p>
<div class="note">
<span class="bold">Note:</span>Report code must be unique.
</div>
</p>
<li>
Build the report by dragging and dropping data objects, noting the
following about Categories, Sorts, Filters, and Layout tabs:
<ol>
<li>
<span class="bold">Categories:</span> Allows the user to select the data
categories (RTFM-Industries tables) that should be accessible on the
report. One or more categories must be selected and will determine the
fields that are available to select on the other tabs.<br />
<div class="note">
<span class="bold">Note:</span> Users will see the tables they're
permissioned to access.
</div>
</li>
<li>
<span class="bold">Sorts:</span> Allows the user to select one or more
data fields used to sort the data. This is optional
</li>
<li>
<span class="bold">Filters:</span> Allows the user to select one or more
data fields used to filter the data. This is optional
</li>
<li>
<span class="bold">Layout:</span> Allows the user to select and order
the data fields that should display on the report
</li>
</ol>
</li>
<li>
To subscribe others to this Documentation Dashboard, enter their email
address in the <span class="bold">Subscriber</span> field.
</li>
<li>Click <span class="bold">Save</span> when finished.
<p>
<span class="bold">Result:</span> the Documentation Dashboard is added
to the list in the bottom panel.
</p>
</li>
</ol>
<h2>Next steps</h2>
<p>
<a href="reports-promote-global.htm">Promote a Documentation Dashboard to Global</a>
</p>
</body>Invoicing setup
<body>
<h1>Invoicing setup</h1>
<h2>Overview</h2>
<summary>
RTFM-Industries automates invoice processing, so you can assign and match invoices with ease. Complete the following setup tasks to configure the workflow.
</summary>
<h2>Prerequisites</h2>
<ul>
<li>
<p>
<a href="../organization/setup-organization.htm">Organization setup</a>
</p>
</li>
<li>
<p><a href="../organization/setup-new-user.htm">User setup</a></p>
</li>
<li>
<p>Administrator permissions</p>
</li>
</ul>
<MadCap:snippetBlock
src="../resources/snippets/view-user-permissions.flsnp"
/>
<h2>Setup tasks</h2>
<ol>
<li>
<p>
<a href="invoicing-permissions.htm">
Grant invoicing permissions to appropriate users
or groups</a>
(<em>required</em>)
</p>
</li>
<li>
<p>
<a href="invoicing-rule.htm">
Configure invoicing rules</a>
(<em>required</em>)
</p>
</li>
<li>
<p>
<a href="invoice-assignment-rule.htm">
Configure invoice assignment rules</a>
(<em>recommended</em>)
</p>
</li>
<li>
<p>
<a href="auto-invoice-process-rules.htm">
Configure automatic invoice processing rules</a>
(<em>required for No-PO invoice workflow</em>)
</p>
</li>
<li>
<p>
<a href="enable-auto-invoice-matching.htm">
Enable automatic invoice matching</a>
(<em>recommended</em>)
</p>
</li>
<li>
<p>
<a href="invoicing-general-settings.htm">
Configure invoicing general settings</a>
(<em>recommended</em>)
</p>
</li>
</ol>
</body>Match an invoice
<body>
<h1>Match an invoice</h1>
<h2>Overview</h2>
<p>
Automatically check for discrepancies between billed and received goods by
matching an invoice. You can perform a <a href="#two-way-match">
two-way match</a>) with an invoice and a PO or a <a href="three-way-match">
three-way match</a>if you also have a receipt. Once an invoice is matched,
its status updates to "Matched" and a linked invoice is created in
<span class="bold">RTFM-Industries > Invoices</span>.
</p>
<p>
If discrepancies are found within your
<a href="auto-invoice-processing-rules.htm#tolerance">configured
tolerance limits</a>, they are automatically reconciled and the
difference is inserted as a balancing line item on the PO. If
discrepancies exceed your configured tolerance limits, you are
prompted to resolve them manually.
</p>
<h3><span class="bold">Additional processing options</span></h3>
<p>
To request information or record an invoice exception, see the
<a href="#Addition">Additional processing options</a> section.
</p>
<h2>Prerequisites</h2>
<ul>
<li>
<p><a href="InvoicingSetup.htm">Invoicing setup</a></p>
</li>
<li>
<p>Invoice in <span class="bold">To match</span> status</p>
</li>
<li>
<p>
"Invoice matching" permission
</p>
<MadCap:snippetBlock
src="../resources/snippets/view-user-permissions.flsnp"
/>
</li>
</ul>
<h2>Location</h2>
<p>
You can match an invoice in two locations depending on the type
of match you're doing.
</p>
<h3>Match to a PO (two-way match)</h3>
<p><span class="bold">Procurement > POs</span></p>
<h3>Match to a receipt (three-way match)</h3>
<p><span class="bold">Procurement > Receipts</span></p>
<h2><a name="two-way-match"></a>Match an invoice to a PO</h2>
<p>
Create an invoice from a PO and check for discrepancies with a
2-way match. The PO must be in <span class="bold">Sent</span> status.
</p>
<MadCap:snippetBlock
src="../resources/snippets/invoicing/match-invoice-to-po.flsnp"
/>
<h2><a name="three-way-match"></a>Match an invoice to a receipt</h2>
<p>
Check for discrepancies with a 3-way match between an invoice, PO
and receipt.
</p>
<MadCap:snippetBlock
src="../resources/snippets/invoicing/match-invoice-to-receipt.flsnp"
/>
<h2><a name="Addition"></a>Additional processing options</h2>
<p>
When an invoice is in the <span class="bold">To match</span> status, a user has the
following processing options that appear above the state machine.
</p>
<h3>Request information</h3>
<p>
To request additional information regarding an invoice, click the
<span class="bold">Request info</span> button above the status line. The point of contact user is notified by email as a result.
</p>
<h4>Provide instructions to the point of contact</h4>
You can provide instructions for the point of contact <em>either</em>
manually on the invoice or automatically through a configured <a href=
"auto-invoice-processing-rules.htm">automatic invoice processing rule</a>.
</p>
<p>
To manually provide instructions, <span class="bold">Edit</span> the invoice, update the
"Instructions for point of contact" field and <span class="bold">Save</span>. These
instructions and the assigned point of contact are saved in the
<span class="bold">Invoicing processing</span> tab.
</p>
<h3>Unassign an invoice</h3>
<p>
To handle an invoice exception found while matching, assign the proper user
to the invoice in the <span class="bold">Invoice processing</span> tab and click the
<span class="bold">Unassign</span> button above the status line. The user assigned to the
invoice is notified by email and the invoice's status updates to "To assign"
for reprocessing.
</p>
<h2>See also</h2>
<p><a href="assign-invoice.htm">Assign an invoice</a></p>
<p><a href="no-po-invoicing.htm">No-PO invoicing</a></p>
</body>Release notes
<body>
<h1>RTFM-Industries v1.1.0 Release Notes</h1>
<p>
The RTFM-Industries v1.1.0 release introduces Automatic Documentation,
changes to our RTFM-Industries REST API, expanded support for prose linting,
and general software updates. Key highlights include:
</p>
<ul class="release-highlights">
<li>
<span class="bold"
><a href="#automatic">Automatic Documentation</a>:</span
>
send a scattered message to a technical writer at the last minute and
documentation will magically appear
</li>
<li>
<span class="bold"
><a href="#api">RTFM-Industries REST API updates:</a></span
>
new methods and attributes added
</li>
<li>
<a href="#Performance"
><span class="bold"
>Tech writer performance improvements: added new indices and removed
redundant reviews</span
></a
>
</li>
</ul>
<h2>
<a name="automatic"></a>
Automatic documentation
</h2>
<p>
The newest feature from RTFM-Industries is automatic documentation! Tech
writers can write all the docs with the press of a button.
</p>
<figure>
<img
src="../Images/automatic-documentation/never-write-doc-again.png"
alt="the secret to never writing documentation again"
/>
<figcaption>
Figure 1. Secret to never writing documentation again
</figcaption>
</figure>
<!-- Conditional text to handle screenOnly and printOnly outputs - this approach is required when providing URLs in release notes -->
<p>
For more information on this feature, see
<a
href="../automatic-documentation/getting-started.htm"
MadCap:conditions="screenOnly"
>Getting started with Automatic Documentation</a
>
<a
href="https://RTFM-Industries/pdf/Automatic-Documentation-Guide.pdf"
MadCap:conditions="printOnly"
>Automatic Documentation PDF Guide</a
>.
</p>
<h2><a name="api"></a>RTFM-Industries REST API (v2.0.0) updates</h2>
<p>
The following updates have been made to the RTFM-Industries REST API
(v2.0.0). For full documentation of this API, see
<a href="https://apiv2.rtfm-industries/docs"
>RTFM-Industries REST API (v2.0.0) Documentation</a
>.
</p>
<ul>
<li>
<span class="bold"
>New method added in Documentation controller:
PrioritizeDocRequest</span
>
</li>
<li>
<span class="bold"
>New attributes added to the Workflow endpoint for Process</span
>
<ul>
<li>WriteTheDocs</li>
<li>EditTheDocs</li>
<li>ReviewTheDocs</li>
<li>MergeTheDocs</li>
<li>ShipTheDocs</li>
</ul>
</li>
</ul>
<h2><a name="performance"></a>Tech writer performance improvements</h2>
<ul>
<li>
Three (3) new indices were added to each tech writer database, resulting
in a 31% increase in documentation
</li>
<li>
Two (2) redundant reviews were removed, leading to increased sprint
velocity compared to last sprint
</li>
</ul>
<h2><a name="Software"></a>Software Updates</h2>
<table
class="software-updates"
summary="software updates"
MadCap:autosort="True"
>
<col
class="col-sm"
MadCap:autosortPriority="0"
MadCap:autosortDirection="ascending"
/>
<col style="col-lg" />
<thead>
<tr>
<th>Issue ID</th>
<th>Type</th>
<th></th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>#1234</td>
<td>Fixed</td>
<td>
Tech writing component references the correct assembly information
</td>
</tr>
<tr>
<td>#5678</td>
<td>Fixed</td>
<td>PDF document no longer shows duplicate sections</td>
</tr>
<tr>
<td>#9101</td>
<td>Improved</td>
<td>
RTFM-Industries satisfaction survey now accepts scores above 100%
</td>
</tr>
</tbody>
</table>
</body>