Category Archives: findability

Single-page docs versus “Click Insanity”


Check out this presentation by Brandon Philips at the 2013 Write the Docs conference. In the video, Philips argues for “single-page docs,” which are entire help systems rendered on a single page. He says that for many technical information sets, like APIs, having all the functions, classes, etc. appear on the same page reduces “click Continue Reading »

DITA’s output does not require separation of tasks from concepts

concept and task thumb dita

One of the main challenges to embracing DITA is accepting the idea that tasks and concepts should be separated. However, despite the common assumption that concepts and tasks should live separately when you follow DITA, actually it’s not the case. You can combine concepts and tasks in DITA’s output through your ditamap. Additionally, you can Continue Reading »

WordPress tip: Create a series of posts


Blogging makes short-form publishing (1,000 to 2,000 word articles) easy, but what if you want to go beyond that, writing long-form content with more substance? For example, what if you want to use a blog to write a book, or a series of essays focused on a particular topic? You could write longer posts, but Continue Reading »

Researching the right keywords (search engine optimization)


Probably the most important decision in search engine optimizing your content is to target the right keywords. If a user searches for X, but your page is optimized for the keyword Y, your pages won’t usually appear in the results. Most SEO experts recommend that you research the most likely keywords your users will search Continue Reading »

Single sourcing and duplicate content (search engine optimization)


One of the challenges technical writers face in search engine optimizing their documentation is deliberating between single sourcing and duplicate content. Google tries to return a variety of unique results, rather the same versions. If you have multiple versions of the same content online, Google will likely just rank the version it perceives as best Continue Reading »

Collapsible header sections — more problematic than helpful


I’m a flip-flopper when it comes to collapsible sections. Sometimes I think they’re great, and other times I think they’re problematic. A while ago I converted nearly all of my help’s subheadings into collapsible sections. I trend toward longer help pages, and the collapsible heading sections seemed like a natural way to provide a kind Continue Reading »