Just Write Click

Technical writing with Continuous Integration and docs-as-code

  • JustWriteClick
  • Contact
  • Books by Anne Gentle
  • Introducing Docs Like Code
You are here: Home / social media / Consistency and community-generated content

November 4, 2009 by annegentle

Consistency and community-generated content

Consistency and community-generated content

I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.

Why consistency?

You may not be a big fan, especially if you’re a creative type, because you appreciate when something interesting and new pops out at you. Unfortunately, you may be one of the few who appreciates something popping out while they’re trying to learn a task or evaluate a concept or analyze a pending purchase. I don’t believe consistency has to mean “dull” but I do believe consistency gives you expected results both in reading paragraphs and in overall organization.

SkyMall – catalog copy example

For some reason, this bit of catalog copy stopped me in my tracks while I was reading the latest SkyMall, waiting for my plane to take off.
Catalog copy for a watch description:

When you want to raise some eyebrows or have an excellent ice breaker for you next sales meeting, the jaw dropping Gforce MatrixPC is your best resource. The stunning design will tell people that you are someone who is confident, secure, and successful; all traits that will attract the right people into your life. The MatrixPC makes everyone aware that you know what it takes in life.

The last sentence was the most jarring, I suppose. Compared to other catalog copy in the same publication, this one struck me as sloppy, not tight.

Little House on the Prairie – narrative example

I’m re-reading the Little House on the Prairie books as an adult after loving them as a child. This time through, though, I’m amazed at the differences in style and tone and the placement of quite technical descriptions of cheese making, contrasted with stories of children not listening to their parents. I didn’t notice these differences in voice and style as a child, but as a grown-up this roller coaster reading was making me a little nauseous.

Then I learned from this New Yorker article, Wilder Women: The mother and daughter behind the Little House stories that Rose Wilder added much of the “flourish” to the books before they would even be considered for publication. Fascinating. The books still hold together and offer a wonderful viewpoint into American history. But there will always be that reader experience of the feeling some paragraphs are misplaced.

How to achieve consistency with community writing projects

On the FLOSS Manuals site, Adam Hyde writes about tone and style swings in the Book Sprints book, saying:

A book can be frustrating if it switches tone in the middle. One author may write in a jazzy, loose style, such as “Don’t panic–we’ll reveal the wizardry in a minute,” while another might write in a more formal style, saying “The following example is complex, but will be understandable by the time you finish the chapter.” Each style is legitimate and useful, but the reader will feel queasy if the tone makes a big swing from one style to another.

I think that “queasy” feeling is one you want to avoid for your readers.

We’ve worked through this for book sprints with a couple of different techniques to ensure consistency in style, tone, and organization.

One is to hire an off-site editor who reviews and modifies new content nightly during a book sprint. By having that person be off-site, they do not get caught up into the intense group dynamics that happen during the sprint, which is such a focused documentation and working group that they may argue unnecessarily about edits.

Another technique is to start writers out with a simple style guide.On the FLOSS Manuals site, each manual has a link to Agreed conventions for writing this manual. It’s not complicated but it does give writers an idea of what expectations they should meet when writing content.

ottoutlineFor book sprints, we outline ahead of time, using simple Post-it notes or even laying out paper printouts on the floor.

These chapter or topic titles will give writers an idea of what type of chunking of information we’d expect for the manual.

And lastly, lead by example. By providing copy in the style and tone that you expect the entire body of work to follow, other writers are more likely to follow suit.

Related

Filed Under: social media Tagged With: community, consistency, editing, writing

More reading

Bubble graph showing sources of developer support data

I’ve been thinking a lot about developer support at Cisco recently, especially for the way the world works today with multiple cloud providers. This post is a re-publish of my talk from over five years ago, but the techniques and tools for listening and helping others are still true today. At Rackspace, we watched several […]

Cisco DevNet is our developer program for outreach, education, and tools for developers at Cisco. From the beginning, the team has had a vision for how to run a developer program. Customers are first, and the team implements what Cisco customers need for automation, configuration, and deployment of our various offerings. Plus, the DevNet team […]

I had a great talk with Ellis Pratt of Cherryleaf Technical Writing consulting last week. Here are the show notes, full of links to all the topics we covered. Podcasts are great fun to listen to and participate in, if a bit nerve-wracking to think on your feet and make sure you answer questions succinctly […]

At the beginning of this year, I worked hard to summarize my thoughts on API documentation, continuous publishing, and technical accuracy for developer documentation. The result is an article on InfoQ.com, edited by Deepak Nadig, who also was forward-thinking in having me speak to a few teams at Intuit about API documentation coupled with code. Always […]

Recently on Just Write Click

  • A Flight of Static Site Generators: Sampling the Best for Documentation
  • Try a GPT about “Docs Like Code” to ask questions
  • Discipline and Diplomacy: Docs in the Open
  • Let’s Find Out: When Do Static Site Generators Do Rendering?
  • GitHub for Managing Tech Docs

Just Write Click in your Inbox

Enter your email address to subscribe to Just Write Click and receive notifications of new posts by email.

Read More

  • Privacy Policy
  • About Anne Gentle, developer experience expert
  • Books by Anne Gentle
    • Conversation and Community
    • Docs Like Code, a Book for Developers and Tech Writers
  • Woman in Tech Speaker Profile
  • Contact

Books

  • JustWriteClick
  • Contact
  • Books by Anne Gentle
  • Introducing Docs Like Code

Copyright © 2025 · WordPress · Log in