Tag Archives: content management

community techpubs work writing

Community Content Strategist

I’m considering a request. It’s a request for a new branch in content strategy. Now it’s odd to even start such a fork when content strategy itself is so new, so nascent that its molds are barely even formed much less any cookie cutting going on. But I think it’s needed.

My request is that we have a branch of content strategy that centers on community.

1. Give us a specialty focus on building community through the expert and strategic use of content.

2. Produce analytical methods that look at requirements for each community persona using content for their goals.

3. Enable the community members to become content strategists themselves, creating, maintaining, and designing killer content in such a way that it grows the community and builds the community and accomplishes the goals the community sets forth.

What’s the business case for a position like this in your company? Let’s start with business case for content strategy:

  • A repeatable process for content creation, publication, maintenance, governance, and careful deletion.
  • Methods for tying content effectiveness to business goals.
  • Measures for people who do this work, based on effectiveness of their techniques in practice.
  • Disciplines to avoid regression and stop old bad habits.

What do I do if I want to call myself a community content strategist?

Let’s start with what I do. I have a pretty unique job here at Rackspace. I coordinate documentation efforts and stack content into meaningful bundles across multiple “core” projects that help organizations adopt OpenStack as consumers or deployers. I manage the documentation project just like a core code project including doc bugs, task tracking, build tool debugging, translation efforts, and all continuous integration aspects of keeping up with a fast-paced software project. I support the wiki, support developers sites that publish doc strings embedded with the code, customize the search engine, seek new content and new contributors, run a monthly doc meeting, participate in all in-person Design Summits held every six months, and ensure the vision for the docs aligns with the vision of the project. The vision is to increase adoption for OpenStack to help Rackspace meet its strategic goals along with HP, IBM, RedHat, and many other member organizations investing in open strategies. I’m creating a repeatable process, and trying to make methods and design tools for content effectiveness. I’ve been doing a lot of work and research into collaborative methods and need to blog about the findings to share.


techpubs wiki

Why Wiki?

In OpenStack-land, the wiki was chosen before I got here. It has a couple of flaws for my vision for open source documentation, which became more apparent when I recently outlined my reasoning for what content goes where. By walking through the “what goes where” talk about documentation and audience, I realized something about the system we have set up (and will tweak more) and it’s this: a wiki revisions a page at a time, but our doc system with comments revisions a site at a time, namely a release at a time. It’s an important distinction to make so that you decide what a web “page” contains. It’s important to be able to articulate your needs for a web page and how it’s updated so that you can tell authors how much information you need in a page.

A page at a time is really tough for ongoing maintenance, when you don’t choose correctly the amount of information in a page. There are also difficulties with the rather immature technology in many wikis. Wikis were designed for simple editing, fast publishing. What if you have a sweeping name change? Anyone doing tech comm in a wiki knows that’s a headache for many wiki systems. What about a final spell check? Page at a time. How about search and replace? Page at a time. And let’s not talk about the times when you have to add an entire column to a table in an ASCII-based wikitext way. Your wrists will revolt, I assure you.

But an interesting expectation for a wiki that wasn’t considered when choosing the wiki is the need for comments on each page. Right now the only web systems for OpenStack that enable comments on a page are the OpenStack blog and the docs site. The docs.openstack.org site is built with DocBook XML with Disqus comments embedded on each page. It’s not quite perfect, as we’re learning as we go that not everyone wants to moderate every comment from every book on the site, and we’re still learning how to turn off hundreds of comments at a time, but it’s a great solution to a specific need. Yes, even the comment system selection needs an information architect analysis before you begin, but that’s the topic of a future post.

Ironically, our wiki doesn’t have a way to comment. So we just use it for project documentation and any comments on a project design are actually done in person at a Design Summit, which is coming up next week. Even with the great opportunity for in-person interaction at the Summit, I get the feeling there are more people wanting to “talk back” and give feedback. And certainly people want to receive feedback, to a point where they specifically bring docs to me and request publishing through the docs.openstack.org system due to the commenting system.

So what this meandering post is coming around to stating is this: You don’t need a wiki to gather feedback on your docs. Find a way to embed comments on each page and a way for collaborators to edit and you’ve got two of the basic end-goals done.

Now, make sure the end goals are known in the first place. It’s possible you need a wiki because your information would be best written a page or an article at a time. This statement is obvious when looking through your hindsight lens but difficult to be disciplined enough to state in the first place. Answer the question “why” about five levels down and it’s likely you have a solution. It may or may not be a wiki, but it’s certain that if you’re producing web content, readers have certain expectations about the content when they come to it.

Elsewhere on the ‘Net

I haven’t done a round up of other places I’ve been writing lately, so I thought I’d offer a roundup of articles I’ve written for other sites.

What I’m writing

10 ways to motivate employees to use your CMS – Fierce Content Management

As a content strategist, what motivations help you meet your content goals when integrating a content system? Often the tool selection gets the most attention, yet the motivation of contributors is going to make or break the success of the project. Motivation is a psychological feature–a willingness to act that precedes behavior. You might think of a points system with rewards as a motivation system, but rewards are only one type of motivation. Read more

Putting the User in User Assistance – WritersUA

People on today’s social web are accustomed to participating in conversations, having a voice, giving opinions, offering reviews, and generally interacting with content and with each other like never before on the web. How can we enable users to respond to or contribute to user assistance? The answer could be a wiki, but a wiki is not required to enable more interaction with users. Here are some specific techniques, starting with the simple and moving towards the more complex, including wiki implementation practices. Read more

What I’m reading

I’m also posting reading items to my delicious.com/annegentle account that might interest my blog readers.

First Steps in Flex Screencasts

The concise examples seem to resonate with how developers learn new technologies.

We meant to do that… (part I) | MsCyra’s Web Development Blog

They say developers learn best by watching (or seeing the results of) other developers code.

How developers learn survey results – interesting

Results from flash developer survey, 100 or so responding. “…the tendency to lean heavily on search to find out about technology and the low number of developers who use classroom training. Online training and videos are fairly popular – although in each case around 50% do not use them.”

WDVL: ‘Users’ Versus People–Understanding What Motivates Online Behavior – Page 2

“As consumers of online experiences are becoming more sophisticated and demanding, understanding and applying psychological and sociological principles in the design of online resources is becoming increasingly critical.”
techpubs tools wiki

Hurdles and Hardships using Wikis for Technical Documentation

After a Q&A on the Facebook discussion page for my book, Sarah Maddox and I had an additional email exchange talking about the difficulties people face when using wikis for documentation.

I believe that many wikis are in the range of “content management systems” or moving in that direction. But there are many difficulties in general with content management. Here are some areas I’ve heard from fellow technical writers:

Access control: Without being able to say who can view or edit what, some wikis are impossible to apply to tech doc due to serving specific business reasons with the content. A customer support article should not be subjected to multiple edits from wiki spammers.

Hierarchy: Without at least 2 levels of hierarchy, tech writers are stymied as to how to use a wiki without hierarchy. Of course. We have complex documentation sets to maintain and hierarchy is a natural way to organize topics.

Version control: The difficulty in maintaining or tracking several versions of a bunch of topics (or an entire namespace/space) to correlate with a software release version is frustrating to many – I’ve heard this is a basic problem for WordPress’s Codex.

Global search and replace – and don’t forget spell check: Writers are used to maintaining giant Framemaker docs where they could spell check and search and replace across large amounts of content. CMSes and wikis don’t make that so easy as before.

Search on the site itself: We’ve all become so spoiled by Google’s search algorithms that any local search engine usually comes up short.

Workflow: Wikis can be weak in workflow, even as simple as “approve or reject” a particular article.

Creating collections: More than just outputting to PDF, people want to single source from a wiki to create collections of articles based on tags, categories, labels, and so on.

Offline access: Many wikis think they’re the end destination for readers, but the classic scenario is “what do my readers do if they need to get on a plane?” One clever solution to this problem would be to offer the wiki on a USB stick – call it a wikiscicle.

Round tripping: Writers are always talking about roundtripping content. I’ve usually dismissed it as not worth the trouble – there wouldn’t be enough contributions that a team of writers couldn’t keep up with. I’ve finally heard a decent business case for doing so – from structured XML (DITA) contained in a CMS to wiki and back again. Translation (to 22 languages) and volume of edits or contributions are the key to this scenario.

One-click publishing (batch processing): On release day, you want to set all topics to released at once, but with many wikis, you have to go to each page one-at-a-time to click them over to the right state for release.

With plugins and advanced wiki engines, these hurdles are easily overcome. But Mediawiki, a popular wiki engine, flunks the first two tests that many technical writers would apply. These are the examples I’ve seen and some of what Sarah has experienced. How does it match up with your viewpoint?

Context and behavior

I appreciated SocialText’s Ross Mayfield describing the various levels of interaction in his One on One interview with Fierce Content Management. The interview reminds me that social context alters behavior and motivations. Think of an intranet situation, where interactions are between bosses, colleagues, direct reports, and coworkers. The goals in this context are to increase productivity and collaboration speed, but corporate culture changes motivations. Then consider the context of an internet site, where interactions and customer relationships can be deepened and enhanced while providing customer service. Contributors to a wiki or any online content management system will certainly vary their behavior in accordance with the offline expectations of them.

I think it was in the book Groundswell that I read a case study where a company brought in a wiki, thinking that Generation Y employees would embrace it. But Generation Y wisely stayed away, because they didn’t have the authority required to make the system work well. Since the higher-ups stayed away from the new system, there was no leading by example, nor was there incentive for the newest, less tenured employees to use the system.

Patrick Davison is a digital artist living in NYC, and he designed the cover for my book. His Ignite talk has a similar theme – considering how your reasons for using a particular site or application (such as Second Life) shapes how you act there. The title is “The Plight of the Digital Chickens” and I think you’ll enjoy it as much as I do.

What are other examples of context shaping online behavior? I’m sure danah boyd has great examples in her papers.

Content strategy – so much to learn

I just ordered Kristina Halvorson’s (@halvorson on Twitter) book, Content Strategy for the Web after viewing “10 things every business person needs to know about content strategy” slideshare.net presentation (by Melissa Rach). Powerful stuff!10 things every business person should know about content strategy

View more presentations from mrsruble.

Reminds me that I need to get cracking on a presentation to supplement my book. I’ll finish up this blog post for now. 🙂

I learned a lot just by clicking through this slide deck so I am anticipating a good education from the book as well.

Content strategists seem to have interesting conversations around the #contentstrategy Twitter hashtags. I learned that PBS has a Chief Content Officer and apparently so does NPR.

I enjoyed the post with notes about content strategy on I’d Rather Be Writing, Three Questions To Start Thinking Like a Content Strategist. The link list at the end is very valuable. Another fascinating set of links for learning is on this Friday content strategy: installment 3 post. It has this excellent warning right up front: Caution: reading the following may make you passionate about content strategy and knowledgeable about recent content news.

So, consider yourself warned. Starting to read this post and clicking through to all the links may lead you through a most fascinating journey to learn more about content strategy.


Managing Writers book includes well-earned experience stories

Richard Hamilton’s new book, Managing Writers: A Real World Guide to Managing Technical Documentation, is clearly organized and a fast read. It often reads like a reference guide, a book you could keep on your bookshelf for years to come.

It is a reference guide in my view, because you can go straight to the table of contents and pick from the list of topics. Want to get your arms around people? Refer to many chapters on Managing People. Need to know insider information on projects before it spirals out of control? Stop the spin machine and go to the pages about Managing Projects. Wondering if the latest alphabet-based tossed salad of acronyms will actually solve your user’s information problems? Hightail it to the Managing Technology chapters. Each of his chapters offers the depth and detail you’d need when faced with a situation you hadn’t seen before. For example, if you’re new to Localization, the information offered will help you ask the right questions and help you get started while avoiding headaches and “time sinks.”

As I read through this book, I felt like I was having a nice long lunch with one of my favorite managers. It’s sprinkled with stories and phrases like “gold-plated Cadillac.” I enjoyed reading about his path to technical publications. It seems many people are eager to leave tech pubs once they start in it. Richard didn’t know much about tech pubs, and wondered if he was leaving the world of technology, but accepted a position anyway. He was willing to learn and stay with it. And stay with it he did, for many years beyond the first two he promised to the hiring manager.

Whether you’re already managing a handful of writers or just starting out, or if you’re hoping to move towards management in technical publications, I think you’ll find this book helpful. Even an experienced tech pubs manager will enjoy hearing another’s perspective and will find many familiar themes that match their own companies and product documentation.

Scott Abel had three copies of the book that he was giving away on Twitter last week – get one before they’re gone, or buy your own copy to read and then keep on your shelf. Like I said myself on Twitter when I first read the book, thank you Richard, for no cat herding references.

Social media and web content writings

I’ve got more blog entries published on the Duo Consulting blog about social profiles, blogging policies, widgets for your web content (I like to call it bling for your blog) and general posts about online interaction and learning. I really enjoy blogging for Duo because it’s encouraging me to research in areas that are important for all content management but especially for the content that people make money on, where they content itself is what people are paying for.

If you are interested in web content, you want to take a look at the Web Content conferences that Duo offers – Tampa Bay in February 2009 looks to be a great opportunity to learn a lot, eat great food (according to one of their conference goers!), and meet like-minded individuals. I can swing a discounted registration your way if you email me via my Contact page.

But Mom, Time Online Is Not a Waste

Teenagers do think differently than the rest of us – you probably knew that already or could have guessed that. But did you know that the way teens develop their skills online is actually being studied by the MacArthur Foundation? They have released the results of their study from three years of interviewing young people and their parents. From the article, they conclude, “America’s youth are developing important social and technical skills online, often in ways that adults do not understand.” The two page summary report is a great read, and I was excited when I found danah boyd in the list of authors. Read more

Why Create Yet Another Social Profile?

Some days it seems like an invite to a particular network spreads like wildfire. First you get a smattering of invites for LinkedIn, and then Spock invites spread, and then, out of nowhere, Naymz appears in your inbox, telling you to worry about your personal brand management. It’s enough to give anyone social media overload. Read more

Widgets for Your Web Content

Bling is usually characterized as offering a special extra “punch” to an ensemble or outfit. Bling is an accessory, which is how I would describe sidebar widgets on your website or blog. Accessories can enhance the main site but can also offer eye candy or a shiny bauble to help the main site gain more attention at the social web party. Coco Chanel is quoted as saying, “Before leaving the house, look in the mirror and remove one accessory.”  Do you need to examine your website to see if it has one or two too many widgets that may detract from your site’s main messaging? Read more

How Did You Get To Work Today?

Have you ever stopped to think about all the signs, infrastructure, access, and coordination it takes just to get people to work each day in a major city? World Usability Day gives us a chance to do just that. The day itself was Thursday November 13. I hadn’t stopped on that day to take notice of what the day is all about so I thought I’d take some time now to look into it. Read more

Blogging and Social Media Policies

A blogging or social media policy describes how an employee or volunteer should represent themselves and the organization online. It also describes whose time and whose equipment may be used for blogging or other social media activities, and it also clarifies when someone is representing themselves, and when they are representing an organization. I’ve written blog entries based on a corporate policy at BMC Software, and it was helpful to know what were the expectations for my time investment and also where privacy lines could be drawn. Read more

From Written Reports to Visualization for Website Analytics

Duo uses a persona-based approach to website designs – which should help answer questions like, “Are potential clients or current clients the most common website visitor and your target for content?” Personas help designers and programmers visualize real people reading and acting on the content they find on a website. But after the design is done and the website is implemented, you have to know what your visitors are doing, how long they’re spending doing that, and whether your website is efficiently “converting” the behavior you want to see – buying a product, signing up for a class, or connecting with other like-minded individuals. So you constantly monitor your website to answer the questions related to your personas’ behaviors. Read more

Searching is Easy – Finding a Community is Hard

Twitter, Twine, and now Twing – I have signed up for all these web applications that start with “Tw!”

Twing is a specialized search engine for deep searches within community discussion groups or forums. So if you want to find niche communities or specialized discussion, actual online conversation, about a topic or a brand, Twing offers a way to search through community content that Google or other search engines may miss. Twing sports a directory listing of different communities so you can click down through the forums that interest you (or may be of interest to your clients or customers). Read more

DITA techpubs work writing

Darwin Information Typing Architecture (DITA) reading list

Here’s a reading list for DITA materials when you’re just getting started. I’ve been fielding some questions via email and IM about DITA lately, and pulled this blog post out of my drafts. I hope it’s helpful.

Learning more about DITA

Getting started with DITA

Structured writing, structured documentation

BMC Case Study featured in The Rockley Report:

Is DITA Going to Tip? By JoAnn Hackos in the CIDM newsletter

Introduction to DITA book cover
Introduction to DITA: A User Guide to the Darwin Information Typing
book by Jennifer Linton and Kylene Bruski.

Planning for DITA Success: How to Set Up the Right Team and the Right
Strategy, Part I, by Steve Manning of The Rockley Group and Su-Laine
Yeo of Blast Radius

Planning for DITA Success: How to Deploy DITA, Step-By-Step, Part II,
by Steve Manning of The Rockley Group and Su-Laine Yeo and Paul
Prescod of XMetaL

10 DITA Lessons Learned From Tech Writers in the Trenches

Updated to add:
ISTC Communicator articles about DITA (2005-2007)


Notes from April 2008 Central Texas DITA User Group meeting

Better late than never, I suppose. I’ve had these notes on my hard drive and want to post them to the cloud of my blog.

John Hunt, DITA Architect in the Lotus Information Development Center at IBM and DITA Learning and Training Content Specialization SC chair, presented Using DITA Content for Learning Content Development at the April 2008 Central Texas DITA User Group meeting. He gave an overview of work being done on the new Learning and Training Content specialization that will be part of OASIS DITA 1.2 release. (Updated to add: see DITA Learning and Training Content Specialization SC for additional information and download links for the Open Toolkit Plug-in that contains the approved specialization.) He then followed up with a live demonstration of creating, assembling, and delivering topic-based learning and training content, delivered both as a SCORM-compliant package and as simple XHTML.

In the room we had about 20 Austin attendees and on the phone, a handful more in Ann Arbor, with John Hunt, our presenter, presenting from Massachusetts. He has worked with DITA for 9-10 years, but interestingly, has met Don Day in person only once.

Learning specialization will become a DITA standard in next OASIS release.

John led with a very recent newspaper article, about re-creating the Jefferson Library – “Re-created Library Speaks Volumes About Jefferson” Amy Orndorff, Washington Post, Apr 11, 2008 (John’s talk was on the 16th!) The library was given to the Library of Congress for $24,000 in 1815. Jefferson had created his own taxonomy – memory, reason, or imagination. Automatically, John wondered if you could parallels to reference, concept, or task. Ah ha!

Fascinating – Jefferson did mashups of books by tearing them apart, even different language books, and then would bind them into new books – reassembly of content 200 years ahead of his time.

Industry context – trends – smaller, faster, leaner for creating and delivering training content.
Content as reusable learning object helps… RLOs (Reusable Learning Objects) were developed at Cisco in the 1990s, similar to legos as building blocks – different structures with the same set of Legos.
LCMS (learning content management system) came into being.

Training can move from a “craft” approach to a DITA content approach, standard.
Craft = every deliverable unique, every context one-of-a-kind
Craft = presentation oriented, labor intensive
DITA = content and deliverables have consistent structures and patterns, so available for reuse and repurposing
DITA = collaboration and reuse becomes the norm

IEEE LOM (Learning Object Metadata) is a standard for the learning metadata domain. See ltsc.ieee.org/wg12/20020612-Final-LOM-Draft.html
Build maps + specialized processing = generated learning deliverables such as tutorials, courseware and e-learning, ILTs, SCORMs=mandated for training delivered to the U.S. Govt. (Dept. of Defense), Textbooks. In case you’re wondering, SCORM stands for Sharable Content Object Reference Model – SCORM is a set of specifications created by the Advanced Distributed Learning initiative (ADL). The ADL website has that SCORM runtime freely available, see www.adlnet.gov/downloads/.

Learning objects contain:
– Instructional objects: overview, content, summary, assessment
– Informational objects: concept, task, reference, also known as Facts, Concepts, Procedures, Principles

5 new DITA specializations as learning types – learningPlan, learningOvereview, learningContent, learningSummary, learningAssessment

Midnight at the OASIS – 32 members on the sub-committee, working drafts, Lang. Spec available for inclusion in DITA 1.2 (Nov 13, 2007)
Specializations of 5 topic types.
Also, three domains are available:

  • Learning interactions domains – open question, true/false, single select, multiple select, matching, sequencing, hotspot.
  • Learning map domain – learning objects and groups, makes learning content available for use in any DITA map
  • Learning metadata domain – makes learning metadata available for use in learning topics and maps.

What does DITA bring to learning content?
Consistency all around (content, processing, delivery)
Can grow as DITA grows – add a Flash object

DITA vision – a platform for collaboration

DITA specialized tags contain “lc” for learning content – lcAudience, lcObjectives, lcDuration, lcPrereqs, lcChallenge (instructions follow that address that challenge), and so on.

Manifest file informs the navigation that is then imported inside the zip file into a sample run-time environment – Advanced Distributed Learning. Has Suspend and Quit buttons, as well as Previous and Continue buttons. Assessment section has questions, true and false with javascript that lets you find out if your response is correct or not.

He showed an embedded Youtube video using the DITA object tag within the Summary object. See Double bonus slide for embed code.

Q: Are you re-inventing the wheel with DITA since scorm and ilm are already standards.
A: Scorm is a packaging and delivery standard. Scorm is silent with regard to content.

Eliot Kimber, Really [ ] Solutions, uses the DITA solution for practice test books for each states – remapped element names to new element names and he gets all the SCORM online assessments pretty much for free because he’s using DITA. Nice.