If you write documentation, you know that sometimes there's not enough time to make a doc shine. Sure, a table of contents with sub-section hash tags would be nice, but who has the time when there's so much documentation still left to write?
Luckily, I just spent a month writing docs and at that scale it made sense to automate as much as I could. So I built a form that does all the stuff that a human can delegate to a computer - build a table of contents, form nice breadcrumbs, add clickable sub-sections, pull out useful links from the content and add them as 'see also' resources. It would be lame if I was the only one who could use this thing, so I added a touch of usability to the input form, vomited some brightly colored vector graphics all over the place (you know you love that kind of stuff) and launched this site so that other documentaristas could enjoy. After churning a couple of docs through the Beautifier, I'm hoping you'll be as hooked as I am.
Below are a few more details on the Beautifier settings and workflow. Oh yeah, and this doc has been Beautified.
The Beautifier will roll through your doc and capture a list of any heading that matches the "heading level" setting. It will then turn each of these headings into links and will stack them all together in a table of contents at the top of the page. The link hashes are created automatically from the titles, so the link to the heading How to pay of credit cards by dressing up like a monkey would be something like #how-to-pay-off-credit. If you want to set a more memorable hash tag, just add something like <a id="monkey-debt" /> somewhere in the heading. The Beautifier will find this and respect it. It feels good to be respected, doesn't it?
<a id="monkey-debt" />
The Beautifier will grab any links within the content and compile these as a list. Any links that are simply numbers - a common method of relative linking between pages on a Drupal-based site - will be added to a Related pages sub-section. All other links will be added to an External resources sub-section. If you set the Base URL for related pages, then any absolute links that start with that path will be added to the Related pages section. Any links pointing to version of example.com will be shunned.
Deciding on a standard for breadcrumbs is tough, there's just not one natural way to do it. And it's a pain, especially when you know the path but don't know how you got there. The Beautifier can help a bit with this, at least for Drupal docs. Just wrap a path in a span class with a class of "crumb" like so <span class="crumb">admin/build/modules</span> and the Beautifier will convert it to Administer > Site building > Modules (admin/build/modules). Not all paths are included (there's a lot of paths about), so do a spot check to make sure there's nothing wonky if you use this feature.
It's a blast to read through some docs just so see how wildly variant people's valuation of headings are. Should you start with H1's, and add sub-sections in H2's? How many tiers should you use? What about just bolding text for a heading? What I found works well is to assume that a document may contain a number of sub-sections, but if you start adding sub-sub-sections, maybe it's time to break the doc up into separate docs. So the Beautifier has a setting called Replace all headings with main heading level, which will take the setting for the On this page section and convert all headings to that level. If you think this is too dramatic, give it a run through a complicated doc and see if it improves usability. I found it did. Plus, it makes the table of contents more meaningful and simple.
Something everyone does differently is calling out a piece of text. On a community-built doc, it can end up reading like a schizophrenic "sales pitch". The most common one seems to be a battle between bold and quotes. Bolding seems to make more sense as a callout, and visually has the effect a callout requires. So, this setting will change all quotes in the text to bolding.
I recently had a write a batch of docs in a temporary location and figure out a way to interlink between them in a way that could be easily replaced out with the URLs where they would finally end up. So, I created an "id" for each doc, and used this for the link href. When they go live, I just need to run them through the Beautifier with a list of these ids along with the URLs to their final home in the Find / replace pairs box. I'll just separate the ids and new URLs with a pipe, like GLOSSARY|glossary-page and put each pair on a new line.
If you're used to using Markdown, it's elegant, simple and easier to write than HTML. If you haven't ramped up on Markdown yet, it's yet-another-language to learn. Some sites like community.openatrium.com support (and expect) Markdown in their docs, whereas drupal.org only allows HTML. I wanted this to be a non-issue, so the Beautifier allows you to convert freely between Markdown and HTML. If you're updating a doc for drupal.org and want to use Markdown, run it through the Beautifier to convert it over, make your changes, and then run it through again to push it back to HTML. If you don't want to learn Markdown today and you want to add a doc to community.openatrium.com, then use the opposite workflow.
Selecting a preset will automatically select options based on the setting. For example, since drupal.org only allows HTML in their docs, it will select HTML for the output, and will add the appropriate base URL.
Please dole out any of the above in the contact form at chrisshattuck.com. Thanks!
This page has been Beautified