You are here
idratherbewriting.com
Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.
What Does Content Re-Use Look Like in a Web CMS?
One challenge I’ve recently been considering is how to handle content re-use on a web content management system, such as Drupal, Joomla, WordPress, or some other web platform. Let’s say you’re writing about ACME widgets and have three different audiences: ACME developers, ACME sales people, and ACME administrators. All your help content is hosted on the same web platform.
In this scenario, you have a lot of different information, much of it overlapping. For example, with your ACME widgets, you have some conceptual info, some strategic info, some configuration info, (more)
Structured Authoring Versus the Web?
I recently listened to the Scriptorium webinar on the State of Tech Comm, which I found well-worth my time. One theme I keep hearing is a trend toward structured authoring. In Scott Abel‘s benchmarking survey (which the webinar uses as a starting point), Scott found that 44% of companies are using structured XML content, with 81% of those companies using DITA for their structure.
Why Long Topics Are Better for the User
In my previous post, Do Short Topics Make Information More Findable, I argued that shorter topics (more)
Do Short Topics Make Information More Findable?
In my last post, which now has more than 70 comments, I noted that authoring with DITA seemed to encourage authors to create a lot of little topics. DITA experts chimed in to say DITA doesn’t constrain users with topic length in their outputs — authors can combine topics as needed. However, one comme (more)
Does DITA Encourage Authors to Fragment Information into a Million Little Pieces?
I’m currently exploring the possibility of authoring content in DITA (using a tool such as easyDITA), publishing to an HTML web help output (through the DITA Open Toolkit), and then importing the output into Drupal (through some Python scripts someone has created).
This sounds like a good workflow to me, but I’ve kind of run into a little problem. I want to nest some tasks into larger topics rather than having the tasks stand alone as their own TOC entries. Reason being, if every task has to stand alone in the TOC, I’ll end up with a TOC that looks unnecessarily lon (more)
How Can a Technical Writer Develop a Love of Programming Code?
Anne Gentle, one of my favorite bloggers, recently wrote about the diverse backgrounds of the technical writers around her — see Developers, Writers, and First Jobs. In her post, she included a job description for a “Microsoft Programming Writer.” It’s kind of a mind-blowing description. Here’s what Microsoft is apparently looking for:
You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connection (more)
How Do You Gamify Writing?
A couple of weeks ago, I wrote about Gamifying Chores. While chores are easy to quantify and measure, activities such as writing have a different dynamic. How do you gamify an activity that has so many complicated facets, purposes, and forms?
Blogging is one way to gamify writing. Blogging introduces game elements to make writing more fun. Blogging makes writing so much fun, in fact, that about 2 million new blog posts are wr (more)
Why Do People Rank High on the MindTouch #Techcomm Influencer Report?
MindTouch recently released their report about the most influential people in techcomm, and I was happy to rank so high.
I’ve had varying reactions to this report for the past several years. The first year MindTouch released the report (2010), I thought it was an ingenious marketing tactic. Within d (more)
Why Does Content Become Disorganized?
Why is it that writing can start out clear and organized, with a coherent logic and order, but then progress toward fragmentation, disarray, and messiness? How do you move from an ordered content system to an unordered content system?
The movement towards disorganization describes the natural direction of many things. Our houses get messy each week and must be cleaned. Our computer desktop gets cluttered and must be ordered. Broken eggs don’t naturally reconstitute themselves into whole eggs. Sand (which was once rock) doesn’t reshape itself into rock.
Content als (more)
Adding Syntax Highlighting to Code Examples Online and in Microsoft Word
If you’re integrating code examples into your technical documentation, a couple of tools can help with this. If you have a web platform like Drupal, you can use Code Prettify (see its Drupal version or WordPress version or regular HTML page version). This module/plugin applies syntax highlighting to your code so that it’s more readable.
Sample Expand and Collapse Code with Twisting Buttons
In my previous post, I wrote about how handy collapsing and expanding sections can be. Although there are several plugins that enable this functionality, it’s pretty easy to create this functionality yourself from scratch.
JSfiddle.net is a neat site that lets you play around with JavaScript, separating out the HTML, CSS, JavaScript, and result into their own quadrant on the page. I created a “fiddle” sho (more)
Evaluating the Usability of Collapsible Sections (or jQuery’s Content Toggle)
After my post on Organizing Page-Level Content, a couple of people asked me about the usability of collapsible sections, also known as content toggles or dropdown hotspots. These are sections that are collapsed upon initial display and then expand when clicked.
Here’s an example:
Read this content Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus iaculis massa eget nulla luctus mattis. Nullam quis purus sed ante interdum viverra aliquam ac mi. Etiam solli (more)Avoiding Quadrant Four
I have a few bad habits I’d like to break. One of those habits is crashing on Friday nights. After working all week, I tend to crash around 8pm and let my brain cells go dormant for a few hours watching mindless television. When the morning comes, I open my sleepy eyes and wonder why I wasted all that time the night before. If I could get those hours back, I certainly wouldn’t spend them watching TV.
Productivity is a perennial topic for me, as I like to set goals and then reflect on why I don’t achieve them. One of the leading authors on productivity, Stephen Covey (more)
How to Organize Page-Level Content
One of the topics I haven’t covered is how to organize content within the same page. If your topics become long and look more like Wikipedia pages, you will have a lot of content to organize — potentially twenty different sections on the page, including both tasks and concepts. What’s the best way to organize all your page-level content?
Although many users, being action-oriented and looking to do something, may skip straight to a task, this doesn’t mean you should mix all your conceptual information with the task information just so users will read it. If you (more)
Gamifying Chores
During our move from Utah to California, we had a lot of things to do – preparing our house to rent, packing, loading, driving, finding a place to rent, unpacking, and the million tasks in between, such as researching areas, renting a truck, and navigating directions. As I have four children under the age of 13, there wasn’t much for them to do, and they kind of had to spectate and wait and watch as we moved.
We’ve never encouraged video games with our kids, but we let them use our iPhones, and the kids started downloading apps and occupying a lot of their time and attention pl (more)
Hello world!
Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!
(more)What I Learned in Searching for a Job
The most common questions I get on my blog are questions about finding jobs in technical writing. While looking for jobs the other month, I realized a few things that I haven’t actually recommended before. Here are a few notes from my recent job search:
- Large companies often select candidates to interview based on employee recommendations. I have a lot of connections with tech writers (784 on Linkedin), so I had quite a few p (more)
Moving to California and Starting a New Job
Big changes are in store for our family. We’re moving from Utah to California, and I’m starting a new job in Redwood City (which is in the San Francisco Bay area) at a company called Badgeville.
Badgeville is one of the leading companies in gamification, which is the practice of incorporating game dynamics and techniques into non-game settings to influence user behavior.
I’m really excited about the new adventures and opportunities ahead. Nexy Friday we’ll be loading up a moving truck and rolling out west tow (more)
Two Competing Help Models: One-Stop Shopping or Specialized Stores?
I spent the past week in California, interviewing with various companies. In preparation for each interview, I studied each company’s documentation as best I could. I noticed two main trends. Some companies group all their documentation together into one massive site. The sites usually have a robust table of contents and include help for most of the company’s products. In c (more)