This is the third installment in a series about the design and development behind what is now Pixel & Tonic. Yesterday we looked at how the site is structured, and how we’re handling URLs. Today I’m going to focus on how I’m managing my product documentation.

When I decided to migrate my FieldFrame documentation from the GitHub wiki to brandon-kelly.com, I was spoiled by a variety of approaches to choose from. I could have simply created a “FieldFrame Docs” weblog, and created a contents tree with your standard {exp:weblog:entries} tag, or done something a bit more interesting using Structure.

But as I’m always looking to bend my own products in strange new ways, what I came up with was quite absurd.

I started by creating that FieldFrame Docs weblog and giving each page its own entry. For the contents tree, I made a new FF Matrix field within my EE Add-ons field group, and gave it two cells: Page (a Playa select related to the Docs weblog), and Alternate Heading (a text field). I wanted to be able to organize my pages into groups, so a row with an Alt Heading set would appear as a heading, and the others would be linked titles. I also created a new FF Matrix celltype, “FFM Hierarchy”, and used that to establish a hierarchy within the tree.

It might look decent, but in practice it’s been a pain in the ass to maintain. Every time I wanted to add a new page, I’d first create the new page’s entry, then go to FieldFrame’s entry, add a new row to the Docs matrix and relate it to the page. If that page was to be placed anywhere but at the end, the hierarchy would tend to get screwed up, and require readjustment. Oh, and when I gave Playa its own Docs section, I had to relate the Playa cell to its weblog as well as FieldFrame Docs, so if I wasn’t careful I could accidentally relate FieldFrame to a Playa Docs page, and vise-versa.

But the worst part was the templates. There was the site/_docs template (routed from site/index and site/_apps), which displayed the current page’s contents:

{exp:weblog:entries dynamic="off" weblog="docs_{segment_1}"
       url_title="{segment_3}{if segment_3 == ''}docs_{segment_1}{/if}"
       limit="1" ... }

{embed="site/_docs_tree" url_title="{url_title}" title="{title}"}
   <div class="col first wide body">
       {exp:textile}{docs_body}{/exp:textile}
   </div>
{/exp:weblog:entries}

And the subsequently-embedded site/_docs_tree was responsible for building the actual contents tree, as well as embedding the site header and footer:

{exp:weblog:entries dynamic="off" weblog="ee" url_title="{segment_1}"
       limit="1" ... }

{embed="site/_header" ... }

<ul class="subnav"> ... </ul>

<h1>{embed:title}</h1>

<div class="col last callout">
   <h3>{title} Documentation</h3>

   <ul>
       {docs_tree}
           <li>
               {if page}
                   {page}<a{if url_title == "{embed:url_title}"} class="active"{/if} href="/{segment_1}/{segment_2}{if url_title != weblog_short_name}/{url_title}{/if}">
                       {title}
                   </a>{/page}
               {if:else}
                   <h4>{heading}</h4>
               {/if}
               {if subpages}
                   <ul>
                       {subpages}
                   </ul>
               {/if}
           </li>
       {/docs_tree}
   </ul>
</div>

{/exp:weblog:entries}

It was a mess.

The Docs Module

Thankfully I decided to use EE2 on pixelandtonic.com, where such an abomination isn’t yet possible, while I wait for… myself… to port FF Matrix over. So this time around, I took the cleanest possible approach: I wrote a new module!

Thanks to EE2’s new module tab API, each of my EE Add-on entries have their own “Docs” tab on the publish page, where I can manage all documentation for that entry, including the hierarchy:

And since my module’s tag pair doesn’t conflict with {exp:weblog:entries}, I can now fit the entire Docs page in a single primary template, ee/docs:

{exp:channel:entries channel="ee" url_title="{segment_3}" ...}
{exp:docs:page entry_id="{entry_id}" url_title="{segment_4}"}
{embed="site/-header" title="{title} - Docs - {docs_page_title}" ...}
{embed="ee/-header" title="{title}" ...}

<div class="content">
    <div class="grid23 clearafter">
        <div class="left">
            {if segment_4}<h1>{docs_page_title}</h1>{/if}
            {docs_page_contents}
        </div>
        <nav class="right">
            {exp:docs:tree entry_id="{entry_id}" base_url="{site_url}{url_title}/docs" selected="{docs_page_url_title}"}
        </nav>
    </div>
</div>

{embed="site/-footer"}
{/exp:docs:page}
{/exp:channel:entries}

In its current state, the module is pretty simple – pages are stored in their own table, and are only given the four fields shown above (Parent, Title, URL Title, and Contents). Page order is defined by drag-n-dropping the pages within the contents tree on the right. The module has two tags, one for outputting the entire tree in an unordered list (not currently customizable), and one for outputting a single page’s contents.

It’s a good starting point, but there are areas for improvement. Once I’m done porting Playa and Matrix to EE2, I’d like to go back and add HTML archive exporting (for on-the-fly downloadable docs) and maybe even release branching.

Release?

Whether or not I release Docs publicly is up in the air. I’ll do it if there’s sufficient demand; otherwise it’ll remain private. So if you think you could use this, sound off in the comments! Include your use case for extra P&T Points (worth about 1/2 a Schrute Buck in today’s economy).

And that’s it for today; thanks for tuning in! This series will continue tomorrow with a look into how I’m managing releases and processing payments, so make sure you’re following @pixelandtonic or subscribed to our RSS feed to be notified about that.