Home
  • About
  • Contact
  • Presentations
  • WordPress Consulting
  • Advertising
  • Guest Posts
  • For Students
  • Jobs
    • Podcasts Book Reviews

    Can Blogs Work as a Web Platform for Help? [Organizing Content 16]

    Wednesday, June 23rd, 2010 Posted in blog | 10 Comments »

    If you know me, you know that I love WordPress. Which is why this post may seem a bit odd to you. Lately I have been exploring BlogEngine as a possible web platform for help. BlogEngine? That little startup blog platform that runs on .NET and Windows? Yes, I will explain in a moment. But first a quick recap on where we are in the Organizing Content series. We left off at 15, and there are nearly ... Read more..

    Organizing Content as Story [Organizing Content #17]

    Tuesday, June 29th, 2010 Posted in blog | 7 Comments »

    With my ongoing series on organizing content, I left off at the question of whether blog platforms would outperform help authoring tools as a way to organize content for web environments. I had a lot of thoughts about that topic, and actually created a blog theme for a documentation project as a test, but recently I received a new project on my plate, and my attention has shifted to another angle on this same series: ... Read more..

    Separating Basic from Advanced Topics: How Twitter Organizes Their Help [Organizing Content #18]

    Thursday, July 8th, 2010 Posted in blog | 2 Comments »

    When you click Twitter's help link, the help content is divided into three categories: Twitter Basics Something's Not Working Report a Violation [caption id="attachment_6807" align="alignnone" width="600" caption="How Twitter organizes their help content"][/caption] This division suggests a mental pattern about how people use help. You have the newbie group. These people are new to Twitter and need a grounding in the basics, such as what an @ reply is versus a dm. The content in this section, Twitter Basics, is simple ... Read more..

    Best Practices for Writing Interface Text [Organizing Content #24]

    Friday, August 13th, 2010 Posted in blog | 15 Comments »

    In this ongoing series on organizing content, we've shifted from organizing help outside the interface to organizing help inside the interface. Moving help inside the interface has many advantages, and there are plenty of best practices for style and format. But the biggest shift in perspective, which I argued in my last post, is to stop differentiating between the interface and the help content. The interface is mostly text. It is an orchestra of words ... Read more..

    Emergence [Organizing Content #19]

    Tuesday, July 20th, 2010 Posted in blog | 8 Comments »

    In the ongoing series on organizing content, we now shift attention to the phenomenon of emergence, and how intelligent, sophisticated systems emerge from relatively simple, unsophisticated parts. I listened to a Radiolab podcast the other day that explored this topic in depth. The hosts related how in the 1800s, Francis Galton visited a county fair where there was a contest to guess the weight of an ox. About 800 people submitted various guesses about the ... Read more..

    Relying on the Wisdom of the Crowds with Help Authoring [Organizing Content #20]

    Tuesday, July 27th, 2010 Posted in blog | 9 Comments »

    The most compelling idea from emergence, which I explained in my previous post, is the surprising wisdom of the crowd. The guesses of 800 people about the weight of an ox at the county fair averaged out to be just one pound from the actual ox's weight. The wisdom-of-the-crowds idea is revolutionary. Traditionally "the masses" are unintelligent compared to the elitist class or the lone genius. But now we have a reverse assertion about the formation ... Read more..

    Principles for Organizing Print Material [Organizing Content #21]

    Friday, July 30th, 2010 Posted in blog | 25 Comments »

    For years I prided myself on single-sourcing both online help and printed guides. When I used RoboHelp, I created custom macros in Word to clean up and adjust the print formatting. With Madcap Flare, I hammered out the print styles until everything looked clean. And then I made a major mistake: I more or less single sourced the online help to the printed guide in a near 1:1 ratio. One day a department manager told me ... Read more..

    The Technical Writer as an Outsider: How Ambitious Are You? [Organizing Content #22]

    Friday, August 6th, 2010 Posted in blog | 23 Comments »

    After our recent reorg, our tech writing group, now split up, has been wondering about the best way to realign ourselves in the new reporting structure, which has yet to be fully defined. Will we end up at the bottom, relegated into some lonely, forgotten corner of the org chart? Will we be grouped with the finance accountants and the secretaries? Or clumped into some other miscellaneous grouping, like a collection of odd socks? My colleague ... Read more..

    The Interface Is Text [Organizing Content #23]

    Wednesday, August 11th, 2010 Posted in blog | 11 Comments »

    In my last post, The Technical Writer as an Outsider, I argued that being an outsider to a project gives you a valuable perspective about the gaps, problems, inconsistencies, and other issues in an interface, so you can do a better job documenting it for other outsiders. After writing the post, I tried to embrace the outsider mindset and hunker down at my desk to go about my work. Working under this metaphor, I realized that ... Read more..

    Organizing for Learnability [Organizing Content #25]

    Wednesday, September 1st, 2010 Posted in blog | 4 Comments »

    Last week I attended WordCamp Utah and spoke with one of the "happiness engineers" who works at Automattic. (Automattic is the the company that provides WordPress.com and also leads development of the open-source WordPress software.) The happiness engineer, Sherri, told me about a new alternative to the Codex and WordPress.com Help for ramping up on WordPress: learn.wordpress.com. At first glance, learn.wordpress.com looks plain and somewhat un-instructive, put together by someone who is straining for offbeat graphics and ... Read more..

    Why Learning Software Is So Hard, and Organizing Content into Levels [Organizing Content #26]

    Thursday, September 9th, 2010 Posted in blog | 7 Comments »

    In a previous post, Anne Sandstrom pointed out that NOBODY does tech writing as a hobby. Many developers program as a hobby. Engineers tinker around in their garage, building things. Other creative professionals, such as artists, photographers, and writers, paint scenes, take pictures, and write stories in their spare time. But I have yet to meet a single person who sits around writing instructions about complicated software applications as a hobby. Why is that? One answer ... Read more..

    Is Rhetoric Relevant? Considering the “Message in Context” [Organizing Content #27]

    Wednesday, September 22nd, 2010 Posted in blog | 21 Comments »

    The other day during a boring moment at work I started looking at PhD programs in technical writing and came across the PhD in Technical Communication and Rhetoric at Texas Tech. What struck me was the emphasis on rhetoric. The program description explains that they emphasize "five broad areas of scholarship in its scholarship, coursework, and initiatives: a) Rhetoric, Composition, and Technology, b) Technical Communication, c) Rhetorics of Science and Healthcare, d) Technology, Culture, and ... Read more..

    Organizing Content for Constructivist Learning [Organizing Content #28]

    Monday, September 27th, 2010 Posted in blog | 5 Comments »

    In my last post, I argued that rhetoric is the foundation of communication. Rhetoric is the practice of fitting the message to the context to get the results you want. In the most common scenario for technical writers and instructional designers, the rhetorical context is a learning situation. You want the user to learn new software or hardware. What's the best way to organize content for learning? In comments on a previous post, Eddie Van Arsdall, an ... Read more..

    Eight Defining Questions that Shape Content Organization [Organizing Content #29]

    Friday, October 1st, 2010 Posted in blog | 15 Comments »

    With recent posts in this series, I started to raise a different question. Rather than asking, how can I help users find this information, I started to ask, how can I help users learn this information? The question you ask determines the strategy you use to organize your content. This may seem like an obvious point, but it's fundamental in determining how to organize your content. In looking over different tech-comm-related disciplines, there are at least ... Read more..

    Findability and The Information Paradox

    Wednesday, January 12th, 2011 Posted in blog | 29 Comments »

    Last year I started a series on organizing content that spanned nearly 30 posts. I want to return to this thread with a summary of why findability becomes an issue for technical writers, and what the information paradox is that we encounter. Then, in an usual ethical twist, I'll explain why findability might not actually be an issue. The Documentation Scenario The help scenario starts out innocently enough. As a technical writer, I document ... Read more..


    Later Entries »
    « Earlier Entries