Skip to content

Formatting Documentation

Jump to bottom Edit New page
Garrett Johnson edited this page Feb 28, 2019 · 12 revisions

Overview

In order to create documentation that matches the quality and innovation of the code we must write well written text delivered with an innovative experience. This experience will be driven by well structured markup which will allow us to 'compile' our documentation not only in HTML but also PDF, eBook and other mediums.

Our documentation markup is based on the new, and still evolving, HTMLBook Spec being drafted by O'Reilly Media. We have added a couple of custom attributes to add some unique features (e.g. tracking updates between versions) but for the most part we should try to stay as close to the spec as possible.

Strategy

Instead of creating one or two large manuals, our 'documentation strategy' is to create numerous concise manuals for each major topic in Rock. For example we would have a separate manual for each of the following:

  • Installation
  • Administrative Tasks
  • Reporting
  • Giving Features
  • Check-in
  • etc.

This is very similar to how MailChimp provides their resource library.

The Structure of a Book

To help build an innovative reading experience we have developed several tools to help us build the documents that will make up our documentation. These tools will be used to assemble the documents and compile them for use in different mediums.

The actual markup will be used to write each 'chapter' of the book. These chapters will be linked to the documents. Our code will then stitch the document together using the chapters creating a dynamic table of contents.

Each book will belong to a category (Installation, Daily Usage, Administration, Technical). They will also have several versions which will match to a specific version of Rock.

Creating a Chapter

Below is the 'stub' markup for a simple chapter that has two sections.

<section data-type="chapter" id="sample-chapter">           
     <p>
         Chapter intro text...
     </p>

     <!-- Sections are the primary unit of the chapter -->
     <section data-type="sect1">
         <h1>Section 1</h1>
         <p>Now is the time for all good men...</p>
     </section>

     <section data-type="sect1">
         <h1>Section 2</h1>
         <p>Now is the time for all good women...</p>
     </section>
</section>

That's it, pretty simple, right? Let's look at some additional items you can add to make your chapters a bit more rich.

Sub-Sections

Yes, sections can have sub sections. Before you add one though really think through if this is needed. We should try to keep the documentation as concise and 'light' as possible. If you must though here is the markup.

<!-- First Level -->
<section data-type="sect1">

    <p>Now is the time for all good men...</p>

    <!-- Second Level -->
    <section data-type="sect2">
        <h2>Sub Heading</h2>
        <p>I just had to have a sub-section..</p>

        <!-- Third Level -->
        <section data-type="sect3">
            <h3>Sub Sub Heading</h3>
            <p>Seriously, just because you can doesn't mean you should...</p>
        </section>

    </section>

</section>

Note that when you add sub sections (limited to five levels in HTMLBook) your heading tag should match the level.

"sect1" -> h1
"sect2" -> h2
"sect3" -> h3
"sect4" -> h4
"sect5" -> h5

Common Elements

Feel free to add the following markup elements to your chapters. This is a subset of the items in the HTMLBook standard, but they should meet all of your needs. If not feel free to check the HTMLBook Spec. If you do feel like an element should be added please talk with the Spark Team so we can ensure the proper styling will be applied for each medium (HTML, PDF, etc.)

Deep Links

Often it will be helpful to be able to link directly to a chapter, section or even a figure in the documentation. Our book assembly scripts will auto-magically insert HTML named anchor tags for you for each chapter and section you create. If you think it would be helpful to add links to additional items, like a helpful diagram, you can add them with the markup below.

<a name="link-name"></a>

Note: these additional named anchors will not generate any UI in the text to notify the reader that they exist. It is up to the author to distribute them to those who may want to use them.

Images / Figures

Use the markup below it insert images to your chapter. Note the use of a versioned filepath. This will allow the same figure to have a different image across versions. More on versions below.

<figure>
    <figcaption>Here Are Your Tools</figcaption>
    <img src="{ImagePath}/1/1.0.0/images/chart-of-tools.jpg" alt="Chart of available tools" />
                    
    <!-- link is:
         {ImagePath} - will be substituted by code to the base path to the images
         1 - the document id
         1.0.0 - the semantic version   -->

    <!-- optional call-out markup, note that the dd element is an optional description -->
    <dl class="callout-key">
        <dt><span class="callout-number accent-bold-color">1</span> Photo</dt>
        <dd>Shows a photo of the current person. If no photo is availabled a gender appropriate   
            anonymous photo will be shown.</dd>
            	
         <dt><span class="callout-number accent-bold-color">2</span> Tags</dt>
         <dd>Tag list for the current person.</dd>
            	
         <dt><span class="callout-number accent-bold-color">3</span> Contact Information</dt>
         <dd>Phone numbers and email address.</dd>
    </dl>
</figure>

You might be asking where you should put your images. We will be storing the images on our Azure file storage account. Please ask for an account if you need access. We highly recommend CloudXplorer $$$ or Azure Storage Explorer free for moving your files to Azure.

Also note the optional call-out mark-up. If you screenshot has call-outs defined (discussed in next section) you can add a call-out key in markup. The dd element is an optional description for the item and is not required. Note that you do not need to add the numbers to the call-outs. These will be added for you based on the order of the dt elements.

Note: At times you may want to adjust the height of an image to help with pagination with PDFs. You can add height 'hints' by adding style='height: 450px' to the img tag. This height will be used when converting to PDF but will be ignored when rendering in the browser.

Screenshots

In an effort to make screenshots as consistent as possible please take all screenshots at a browser (viewport) resolution of 1280x960. (We suggest using the Window Resizer chrome plugin to make this super easy.) When appropriate be user that the logged in user has the name of Alisha Marble. Also please ensure that the Admin Bar (at the bottom) is hidden. This may mean that you need to hide it by editing in in page CSS.

Also, if your screenshot is going to data shown be sure to use the official test data:

Screenshots should be saved in a png format with an 8-bit color depth if possible (24-bit is acceptable for screenshots that require transparency or need the additional colorspace to display in a high quality manner.

If your screenshot needs call-outs please use the callout.psd template to get the common size, color and font call-outs.

Table

This is just your standard HTML syntax.

<table class="table table-bordered">
    <caption>Table Caption</caption>
    <thead>
        <tr>
            <th>First</th>
            <th>Middle Initial</th>
            <th>Last</th>
        </tr>
    </thead>
    <tbody>
        <tr>
             <td>Alfred</td>
             <td>E.</td>
             <td>Newman</td>
        </tr>
    </tbody>
</table>

Note: Should you have the need to add a table with no borders simply removed the table table-bordered CSS classes from the table.

Notes / Admonitions

HTMLBook supports five types of notes (Notes, Tips, Important, Caution and Warning). Below is the mark-up to use for adding a note to your chapter.

<div data-type="note" data-note-type="note, tip, warning, important, caution">
    <h1>Note:</h1>
    <p>Just a note...</p>
</div>

Below we outline when to use which:

  • Note - Use to extend or add an additional point to a topic.
  • Tip - To give a suggestion in a topics usage.
  • Important - To highlight a point to remember such as a limitation.
  • Warning - Used to notify the user of possible unintended consequences.
  • Caution - To notify that an action is dangerous and could cause undue frustration (e.g. data being deleted)

Video

Video, why not! The syntax below will allow us to show the video in mediums where it's easy and appropriate and have a fallback for those that are disconnected.

<video id="asteroids_video" width="480" height="270" controls="controls" poster=">>/1/0/7/images/fallback_image.png">
    <source src="video/html5_asteroids.mp4" type="video/mp4" />
    <source src="video/html5_asteroids.ogg" type="video/ogg" />
    <em>
        Sorry, this video element is not supported in your
        reading system. View the video online at http://example.com.
    </em>
</video>

Notice the versioning in the poster element.

Note: The syntax on this one might need to change a bit. We'll know more when we get to compiling our first PDF document with a video in it. Can't wait, can you?

Data List

Yeah not much exciting here... but, it is supported in styling.

<dl>
    <dt>Definition List Title</dt>
    <dd>Definition List Data</dd>
</dl>

Block Quote

Again nothing new.

<blockquote data-type="epigraph">
     <p>When in the course of human events...</p>
     <p data-type="attribution">U.S. Declaration of Independence</p>
</blockquote>

Code (inline)

Used for inline markup, variables, functions, control references, etc.

Use the <code>Rock:Grid</code> in your block when...

Code Block Example

Bet we'll have some of these... no? For when you need a square block code example.

<div data-type="example">
    <pre data-type="programlisting" 
data-code-language="<aspx, csharp, css, html, javascript, js, sql, xml>">{% if Person %} 
	    {% if Person.BaptismDate != '' %}
	        {{ Person.NickName }}, remember the joy of your baptism? Share that joy
	        with a friend who hasn't yet taken the plunge at one of our upcoming
	        baptism events!
	    {% else %}
	        {{ Person.NickName }}, now is the time! Don't put off baptism any longer,
	        take the plunge at one of our upcoming events!
	    {% endif %}
	{% else %}
	    Take the plunge at one of our upcoming baptism events!
	{% endif %}</pre>
</div>

Note: Again, this markup might have to change.

Make sure you don't include any newlines after your opening pre tag or before your closing pre tag. Otherwise you'll have extra lines in the final styled document and it doesn't look good.

When the docs are generated the ColorCode library is used (CodeColorizer().Colorize(...)) and any of the following languages will be syntax color highlighted: aspx, c#, csharp, css, js, javascript, html, sql, and xml.

Action Labels

When writing technical documentation it is often necessary to encourage the user to take certain actions like pressing a button or navigating a menu structure. To help with the aesthetics of these actions we have defined the following inline styles for specific actions (please let us know if additional ones would be helpful).

<!-- A native OS button press (used primarily for setting up Rock) -->
Press <span data-type="action" data-action="action-os-button">OK</span> when complete...

<!-- A Rock specific button press (used in the Rock webapp) -->
Press the <span data-type="action" data-action="action-rock-button">Done</span> button to save your work...

<!-- A reference to another Rock manual () -->
For more information see the <span data-type="action" data-action="action-document-ref">Admin Hero Guide</span> .

<!-- Navigating a user through down a menu structure path -->
To add a person to a new security role go to <span data-type="action" data-action="action-navigate">Administration > General Settings > Security Roles</span> ...

Note: Be careful when considering adding actions. Ask yourself is telling the user this step really necessary, or are they able to intuitively figure it out. We do not want our documentation to become a long list of "Push this... Then Push That... Finally Click This".

Highlighted References

When writing your documentation you will need to reference different types of elements in the application. Examples of this would be specific pages (‘Person Profile’), fields (‘First Name’) and UI elements (‘Smart Search’). These elements should use special styling to help add context to the reader that they are specific references and not general descriptions. A list of the required reference callouts are below with sample markup.

<!-- Reference A Specific Page -->
The <em data-type="reference" data-reference="reference-page">Person Profile</em> contains...

<!-- Generic Highlighted Reference -->
A person's <em data-type="reference" data-reference="reference-highlight">Baptism Date</em> is listed on...
Use the <em data-type="reference" data-reference="reference-highlight">Rock.Web.UI</em> namespace...
Look in the <em data-type="reference" data-reference="reference-highlight">RockWeb\Plugins\</em> folder...

Page Breaking for PDF

For this most part you should not have to worry too much about page breaking. Each chapter will start on a new page. The generator will also ensure that images do not get split across a page. Should you want to enforce a page break in some specific place you can add the .page-break CSS class to an element. This will page break before the element.

You may also wish to keep certain content together on a page. The CSS class .page-break-avoid will attempt to keep the element it decorates from being split across a page break. The only time this will not be enforced is if the element is larger than a single page. You may be tempted to add this to tables so as not to split the table header from the content rows. The PDF generator is set to repeat the header across page breaks so this should not be necessary.

Versioning

Rock will not stand still. It will grow and evolve. This means our documentation will have to evolve with it. Below are topics that address how we'll make sure our documentation not only stays current but also works to enhance our updates.

Note: Versioning is not a part of the HTMLBook standard. If it doesn't work, well we can't blame them..., but it will work, and it will be AWESOME!

How To Version

As new versions of Rock are released the manuals will be versioned with them. For each minor version a new set of documents will be produced. This will be done by cloning the previous version's document in both the database (document and chapters) and filesystem (images). See Adding a New Version of Documentation for details.

Tracking Updates

OK, so we have our documents and McKinley 1.0 is out the door. Then 2.0 is released. Obviously, the manuals will need to change to reflect all of the new goodies. But, if I'm a good user and have read all of the manuals to date I'm probably not looking forward to trying to find out what might have changed since the last version. Talk about being punished for being good... Fear not, truth and justice will not allow a good person to be punished.

We have two ways to help the user understand what has been updated. Lets look at each...

Update Summaries

Each document will provide a brief summary of the changes in the manual for a specific version. (TODO: figure out where these summaries are stored). These summaries should take the format of:

<div data-type="update-summary" data-update-tag="0.5.0">
    <p>Here is a list of updates in version 0.5.0:</p>
    <ul>
        <li>Update 1</li>
        <li>Update 2</li>
        <li>Update 3</li>
    </ul>
</div>

So you're probably thinking... boy that's innovative... but read on... By default these summaries won't be shown (hang on...). Instead each document will have a dropdown box in the upper right corner labeled "Show Updates Since". When they pick a previous version it will show the summaries that are newer than the selected version.

Oh... it get's better...

Update Highlighting

When the user selects a previous version from the dropdown the document will also highlight each area of the document that has changed since the selected version. How does it know what changed? You're going to tell it.

When a section, table, paragraph, or any HTML element has been significantly updated you will need to mark that fact with the data-update-tag attribute.

<section data-type="sect1" data-update-tag="1.1.1">
    ...
</section>

The version value is the version that the change was made in. You might be thinking, "What if it was changed in both version 1.1.1 and 1.1.2? Multiple versions are allowed in this attribute.

<section data-type="sect1" data-update-tag="1.1.1 1.1.2">
    ...
</section>

Remember this attribute can be on any element.

<figure data-update-tag="1.1.1">
    ...                
</figure>

<p data-update-tag="1.1.1"> ... </p>

<span data-update-tag="1.1.1"> ... </span>

The CSS/Javascript on the page will simply change the background color of these items to a subtle highlight color to show the update.

We need to be really selective on what we mark with the update attribute. A simple wording change or typo fix would obviously confuse or irritate a user. Only moderate to significant changes should be called out. When trying to decide, think "Would a user say, 'Oh cool, that's new!'?". If not, move along, there is nothing to label here.

Note: The actual value of the update (e.g. 1.1.1) might need to change. Something we still need to discuss. To date this has been prototype and it looks like it will work well.

Add a custom footer
Clone this wiki locally