Tag Archives: writing

techpubs wiki writing

Must Read: Confluence, Tech Comm, Chocolate

“Who cares about printing money, let’s print chocolate!”

–Chapter 23, Driving Wiki Development, Confluence, Tech Comm, Chocolate

Do you need proof that Sarah Maddox, author of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, is a complete chocolate and wiki expert? Let me tell you, she knew that one day we will print chocolate in our (industrial-grade) kitchens. And sure enough, that day has arrived! And so has her book. It’s a wonderful addition to the XML Press family.

Sarah has an amazing knack to start at the beginning and introduce wikis in a friendly way even though she has been living the wiki life for years. She writes an introduction to wikis in an approachable way and ensures the reader knows the context is technical communication. But for me there are technical details revealed that offer the best chapters of this book. There is the deep technical dive into “building online help” especially her case study of web-based, context-sensitive online help. This solution should rock your world if you’re looking for a cross-platform web delivery of your online help. Her chapter about “a day in the life” of the wiki is just what you need to understand how this delivery and collaboration solution is different from “ordinary” technical writing. And I thoroughly reviewed and enjoyed “Giving your wiki wings.” Wikis with wings are the way technical writers will show their value to the world. I especially appreciate the chapter “Driving wiki development,” where Sarah is clearly honest about gaps in wiki functionality and how we can actually improve our experiences with wikis.

This book is an important, essential addition to the professional writer’s bookshelf. I’ve already whole-heartedly recommended it to an entire team of Rackspace writers and to all my Austin-based writer friends who have listened to me talk about the changes in the industry over the years. I want to recommend it to all of you as well. This book offers both visionary inspiration and the nitty-gritty technical details for all of us working in this web-centric world. I have so much respect for Sarah’s work on this book. Her enthusiasm for the wiki way shines through each page – web page and printed page. Pick up a copy, devour it like a chocolate bar, and drive collaboration for technical content.

Buy now at Barnes and Noble

Buy now at Amazon.com

techpubs writing

Open Advice Book Now Available

Open Advice coverWhat we wish we had known when we started working on free open source software (FOSS) – that is the premise of this essay collection, Open Advice. What’s especially interesting to me after having read all 42 essays is there isn’t really a pattern like you’d see when looking at “what I would tell my younger self” such as “believe in yourself” or “don’t worry about what others think.” Those themes do come through, but the heart of the collection centers on open source projects, software, users, coders, and the myriad roles that make an open source project great. It’s a collection of great stories and great experiences.

One theme that stuck out to me was “I wish I had been less arrogant.” So many people, women especially, can be put off by the attitudes displayed by an open source online chat room or mailing list. I know I’m happy to see more women’s names on the OpenStack mailing list, asking and answering questions. I’m also happy to note that the OpenStack community is polite, professional, and welcoming to all.

An essay that fascinated me was “27 Things I’m Happy I Didn’t Know” by Alexandra Leisse. Ignorance is bliss in many arenas, open source is no exception. Sometimes learning from mistakes is the best lesson.

I also loved the “Never on a Friday” section of Sally Khudairi‘s essay that leads with “Everyone is a marketer.” She launched a new homepage for W3C on a Friday then boarded a plane for Paris. She landed to a flood of messages about a particular tag choice. Fabulous story.

Dave Neary‘s essay about conference planning, “Getting People Together,” has a detailed section about budgets and funding plus content and parties. Valuable and practical, this essay should be required reading for both conference planners and attendees.

What did I write about? Documentation and My Former Self is the title, and in it I realize how many contradictions I’ve discovered on my journey. Often, adding more and more observations will bring a flip turn to my stance on a documentation strategy. Fascinating.

The Open Advice book in PDF format is downloadable for all and I’d encourage you to read it, enjoy it, learn from it, and share it. Then, join in an open source community with those lessons already learned.

Exciting Future for Collaborative Printed Electronic Books

The future of the book is in your hands from Sourcefabric on Vimeo.

Sourcefabric builds open source software to support independent media worldwide. On February 14th, we’ll announce our tool to help people and organisations write and publish great multi-platform books.

Write and publish great books ready for iPad, Kindle, Nook or print within minutes. Write, translate or reuse content by yourself or with others and let the platform take care of structure, formatting, licensing, versions and export to book formatted pdf, epub, odt or html.

Share, reuse and remix content, chapters or even entire books. For example, import an epub from Gutenberg or a colleague’s textbook, rework and then publish to archive.org, lulu.com or another bookmaking community!

February 14th 2012. The next chapter in publishing.


techpubs tools writing

Crowdsourcing Inquisition

I consider myself a curious person. I was constantly questioning as a kid, much to the chagrin of my fifth grade teacher. I recall that he wrote in my yearbook, “Keep asking questions, but when you ask, listen and learn.” How fortunate I could become a professional technical writer, where curiosity and asking “how does that work?” is a requirement of my daily work. Of course, the listen and learn portion for my 30+-year-old self is, “write it down before you forget!”

What’s nice about working on OpenStack at such an early stage is that others are asking really good questions also. We started the project using Launchpad’s Answers feature for OpenStack projects. Launchpad Answers is a rudimentary question and answer system that’s a blend of a mailing list and a forum in one, attempting to help projects create community support sites. (We all know that building a community support site is about people, not tools, so I’ll just repeat that mantra here for emphasis, people over tools.)

With configurable notifications and the ability to turn a question into a bug, it acts as a substitute for overly-eager users filing tons of non-vetted bugs. I don’t find it as advanced in the community equity model as say, Stack Overflow’s Q&A sites, but you do earn “karma points” for answering questions, and you can comment on a question or ask for more information. Also, the person asking seems to have the upper hand for marking a question as answered. We’ve very recently started to explore the use of a forum rather than the Launchpad Answers area. I’m hoping we’ll see as much curiosity in the forums as we have seen in Launchpad Answers.

To me, the upsurge in community support sites means that the questioning nature of a technical writer can be spread out among even more questioners. Even if a user does not consider themselves to be technical writers, they are doing some of the work of a technical writer. People in the real world, trying out OpenStack, are coming back with all sorts of questions. Plus, the questions and answers can be searched for later reference. It’s a gold mine of technical info and specific scenarios. The challenge for the technical writer is to sift through the questions and answers and determine relevance for their audience and determine the majority use, eliminating edge cases. The challenge for the system itself is

And in the theme of yearbook quotes, how about this one? “Better ask twice than lose your way once.” My hope for OpenStack is to build a community support site where duplicate questions are not dinged but search-worthy, there are no dumb questions, and the questioners listen and learn, and then pay it forward.

Booki in the running for a Drumbeat Award

Adam Hyde, founder of FLOSS Manuals, the community documentation group that makes open docs for open source, just announced some exciting news on the FLOSS Manuals Discuss list.

…we got booki into the Drumbeat
Open Web Award…ok. Thats great news! Well, now we need to get votes
since there are 3 projects we stand a very good chance to win the 5000
cash (which we will use for a code sprint)

so…if you want to vote go here:
Open Web Publishing

Register and vote!

This is exciting news! Registration and voting was a bit wonky when we first sent people to the site but I think it’s all worked out now and we have a great shot at this. Please help out if you are so inclined.

The timing of this announcement seems well-aligned – just yesterday I wore the “Adopt Mozilla” t-shirt that I received for donating to the Open Web fund.

So, whether you support a baby Mozilla or a baby Booki, let’s keep the web open and support open documentation and publishing while we’re at it. Read more about Booki at the Booki blog.

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

Wikis for technical documentation – Cliff’s Notes

If there ever could be a Cliff’s Notes for the wiki chapter of my book, I think I’m writing it now. I’ve been working on a great project with MindTouch. I visited them for a focus group with other technical communicators and technical support pros back in February in San Diego. We had open source community documentation represented, we had the health information industry represented, cloud computing, and high tech software writers, Agile writers, and document collaborators. It was a great time, discussing tips, tricks, and the trials of managing lots of content with specific purposes in mind such as learning, education, customer support, technical support, and internal collaboration. The write-up for how to run a focus group of this type is quite good – see Seek Omega: How to hold a Professional Focus Group that Produces Quantifiable Results.

After such a great session, we all continue to talk online thanks to one of the members setting up a LinkedIn Group, and MindTouch also invited us to work on a project to write up specifications for using wikis for technical documentation. We’re basically creating best practices using wikis for documentation, such as:

  • templates, such as DITA’s concept/task/reference as well as FAQ and solution guidance through multiple tasks
  • tags for workflow, assigning tasks, editing, and categorizing pages
  • content collection and curation
  • reports that assist with content curation and community documentation

I’ve been circling back with the members of the focus group while I write these specs, and working with Steve Bjorg, the CTO for MindTouch. His attitude towards development is,  create something with a sense of openess and collaborate with users as early as you can. It’s a refreshing way to make software. He describes these first go-rounds as the “Cliff’s Notes” for creating technical documentation with wikis. It’s not as robust as other solutions yet, but it sure does have features that are exciting glimpses at the future of documentation. I’ll post more in the coming weeks and months as we round out the features.

Social media, conversation, and writing style

What are some pointers for developing a style guide for writing on the social web or for certain social mediums? I discuss style guidance at length in chapter 7 in my book, which is titled Finding Your Voice. In fact, I read from chapter 7 for my book reading at South By Southwest Interactive last week! Definitely finding my voice on the couch on stage.

If you’re working on a style guide for social media, you might find this collection of links that are all the footnotes from that chapter from my book, Conversation and Community: The Social Web for Documentation. All the references from that chapter are on delicous.com/annegentle/chapter7, but I think the most relevant are the ones I bookmarked very early on:

  • A List Apart: Style Guide – Be concise, reader-centered, and seek clarity. One quotable line from it is “You need to get in, score, and get out.”
  • Writing for the Social Media Everyman | Copyblogger – “The social media everyman is looking for an entertaining diversion, while being receptive to learning something new if presented in an “edutainment” format that ties the lesson into popular culture.”

I think the main points to remember when developing a style guide are to value highly clear, concise, to the point, honest, and attention-getting writing. Social media seekers read and scan quickly and the payment in the web economy is via links which translate to attention.

The Elements of Style turned 50 years old last year, and has sold 10 million copies. Nearly all our copywriting guidelines could be traced back to that original “little” book, an “attempt to cut the vast tangle of English rhetoric down to size and write its rules and principles on the head of a pin.” (Quote from an article in The New Yorker in 1957)

Web writing hasn’t changed the basics, rather, the web has increased style’s relevance to successful communication.

Become a fan of my book!

I’ve put together a Facebook page for my book, Conversation and Community. I’ve had requests for a place for people to talk about the ideas in the book, and after talking it over with others, I settled on Facebook as a good place to bring together all the different sorts of communicators who have found my book helpful. From a pastor in Michigan to a small business on the west coat, to all the technical communicators who have found it useful, let’s gather together to socialize and talk about this shift towards enhanced social communication techniques.

I Am Who I Am

I’m late to write up my thoughts on Gordon Mclean’s post, Strange Bias, but I give him a belated thumbs up for great self-inspection and data query in the post.

My take? I read ““Why James Chartrand Wears Women’s Underpants” on Copyblogger in December. It’s a great survivor story that you should read in its entirety, but the gist of it is that James is a pen name for a woman freelance writer, who writes the popular blog Men with Pens. Merely representing herself as a man made a real difference in her career trajectory. I was shocked, though, that she never had to talk to clients on the phone and that she never went to conferences or spoke at conferences.

It made me wonder if I’d have 10 times the subscribers to my blog if I had started in 2005 as Tom Gentle. It really did. But we are who we are, and being genuine and transparent is all part of my blogging experience. Many of the opportunities I’ve had in the past 4-5 years are somehow related to my blog and the work ethic it requires to maintain.

And to answer Gordon’s question, “is it just me?” I’d say, my experience with tech pub teams I’ve been on are that men are the slightly minority gender. If you believe Quantcast web stats about the STC website, you see that 61% of site visitors are female. I’ve also observed more women at tech comm conferences than men.

But, socializing being, well, social, means you tend to relate to people like yourself, right? So followers, friends, and fans, being self-selecting as they are, may prove that men follow men and women follow women. I think Twitter certainly reflects this tendency, since research shows men follow men on Twitter. And bloggers use Twitter far more than the general population (See the pie chart on the Day 5 report).

If you read Technorati’s State of the Blogosphere you see that 2/3 rds of all bloggers are men. So the 55% blogs written by men that Gordon reads actually differs from the predictive 66% overall population. A great observation, Gordon, well done.