How to Document your Stylesheets

by Karie

You're working on a big project or a book using DITA, but your boss asks you to change the style of the font at the last minute. This was something you had set months prior and you don't remember how you did it or how to change it now.

This is why we like to recommend documenting your stylesheets. Think of it as an investment in your future time. Don't waste time trying to figure out how you did something as simple as put page numbers in, record it through screen shots.

One way is to create a graph in powerpoint laying out how this document was set up. The red lines show a visual of how the  pages are set, starting at the left going to the right you have the page; sets, types, regions and generated contents.

The empty boxes aren't empty, each one actually represents a power point slide. Here the screenshots represent how I built the pages in DITA. Starting on the left I have page sets, then page type and then page regions. You can see a preview of the page to the right, here it is the TOC (table of contents) Right page. The blue lines show the path you took to get the 'TOC Right' page set up so you can easily retrace your steps.

You're looking at the 'Page Regions' part of the graph. Starting at the left is the page; position, text and borders. The blue line at the bottom takes you to the generated text.

In the generated text we're looking at the generated text for the TOC Right page header. In the editor view you see the generated text marker, but in the screen shot to the left you can see the actual markup. It's important to have both of these pictures side by side so that you can really see what the value is.

Capturing and organizing your work as you go helps to prevent wasted time back tracking your previous work and having re-train yourself as to how you did something so easy as change a page number.