Subscribe to RSS
FLOSS Manuals book store now open!
I went out for a run this morning and realized it has been a year this very week since I started my volunteer work with OLPC. This project was my first foray into the open source world from a contributor standpoint, and I can’t believe how it has paid back at least tenfold in the people I’ve met, the lessons I’ve learned, and the technology I’m now acquainted with.
What did it take? For me, time and faith and trust in others.
This is an amazing day and it has been an amazing journey. And what is significant about today? We now have a FLOSS Manuals bookstore and we now have a real, hold-it-in-your-hands, put-it-on-your-bookshelf, book. With a cover designed by someone who works at MOMA no less. (Wow!) With content carefully authored by people who learned and knew enough about the technology while also considering who would read the chapters and what they want to do with the technology.
I’m happily and proudly displaying the distributable FLOSS Manuals bookstore on my blog - see the sidebar on the left? That’s a bit of HTML code that anyone can display and host a portable virtual book store on any web site. Here’s the code.
<style>
@import url("http://en.flossmanuals.net/bookstore/bookstore.css");
</style>
<img src="http://en.flossmanuals.net/bookstore/bookstore.gif"
style="margin-bottom:5px;">
<script type="text/javascript"
src="http://stores.lulu.com/feed.php?fStore=flossmanuals&fFormat=js"></script>
You can always download the PDF for free, but by buying a book you support the FLOSS Manuals project and help support the uptake and usefulness of free software by providing free documentation. Your money is well spent as these paperbacks are high quality and can take wear and tear. My hope is that people will read it and that the book will be passed on to the next learner.
My DMN Communications Podcast Now Available
Scott Nesbitt and Aaron Davis have a great podcast show called Communications with DMN. I love these guys’ “brand of insanity” as Scott puts it.
We had a great time talking about wikis, FLOSS Manuals, and the recent One Laptop per Child BookSprint for about an hour. They had prepared at least two pages of questions and still had more to ask! It was great fun. Listen for yourself, please. Feel free to comment here or there, either place, I’d love to hear feedback on this interview.
Upcoming presentations in Austin and Houston
I’ll be presenting Documentation as Conversation at the Austin STC meeting Tuesday October 7th.
Austin When
Tuesday October 7th
6:00 - 6:30 PM: Networking
6:30 - 7:30 PM: Program
7:45 - 9:00 PM: Networking dinner
Austin Where
UT Commons Center - Room 1.138 [Map]
Then in November I’m going to make the trip to the Houston STC Meeting Tuesday November 11th.
Houston When
5:30 - 6:30 PM: Networking
Houston Where
Houston, TX 77098
http://www.ichotelsgroup.com/h/d/sl/1/en/hotel/hougp?_requestid=1732305
Documentation as Conversation: Working conversation and community into documentation using social technologies
Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well, play with technology at home, or learn something new in a classroom setting.
Instead of concentrating on single sourcing or the tools of the trade, this talk describes how you can think about documentation and user assistance in a conversational way, perhaps with the help of some social networking applications. I’ll also discuss the in-person FLOSS Manuals BookSprint as a use of a wiki paired with a community event to gather together writers to accomplish documentation goals for free, open source software projects.
FLOSS Manuals BookSprint captured in video
Talk about user-created content. I’ve become a video producer, amateur being the kindest description I can come up with for myself.
I haven’t been posting as much lately because I’ve been working on this video to describe FLOSS Manuals and the recent BookSprint. Take a look and let me know what you think.
Welcome sign
Looking at the event in the rear view mirror with the camera off, I realize that I’m still blown away by the outcome of seven books being print-ready in a week of writing with about another week of clean-up. Edits are still coming in, which I think is great. The content is continually improving.
Adam Hyde also recently posted to the FLOSS Manuals discussion list that he has solved many of the widows and orphans problems he had with the pretty-print PDF versions. So we’re ready to start taking orders for books. Stay tuned for the best way to order your own copy, we’re working out the logistics.
Also, there’s a new Help Activity available for download that contains all our content from the Sprint. Now that is an exciting outcome - online help that goes right on the laptop.
Podcast production at talk.bmc.com
It went all too quickly, but for the past few months I’ve been working with Tom Parish on podcast production at talk.bmc.com. I’ve since decided I can’t juggle quite that many balls in the air, but I’m pleased with how these podcasts turned out. I learned a lot about the behind-the-scenes work of recruiting interviewees, finding topics, and producing the shows. With an assertive goal of four shows a month, you have to be constantly looking for the next person to talk with, setting a schedule, and researching the topic well enough to come up with a set of 5-7 questions to fill a 15-30 minute recording.
Our goal with talk.bmc.com/podcasts is to produce educational shows about Information Technology, ITIL (Information Technology Infrastructure Library), which is a set of standards published to help you tighten up your IT department and align it with the whole company, and Business Service Management which is a revolution for how IT departments can run in order to tie technology into business goals.
William Hurley - Seeing Transparency through Open Source and Enterprise Software
Mary Nugent - Preparing your Business Services for the Future
Dennis Drogseth - Value Proof for CMDB Deployments
Tom Bishop and Dan Turchin - The Mobile IT Worker – They Walk, Talk, and Keep Businesses Running
Mainframe Trends in Enterprise IT for 2008 with John Albee and Mike Moser
Peter Armstrong on Guiding Principles to Changing Behavior and Speeding the Adoption of BSM and ITIL
Doug Mueller - Taking the Service Desk to the Next Level
The links above go to the show notes for each show, which is basically a blog entry to entice people to listen to the show. My favorite is probably William Hurley with Mary Nugent a close second. And the Mobile IT Worker has some fun stories in it.
The neat thing about podcasting is that it lets people tell their stories. Stories are very difficult to convey any other way, although the Google Chrome comic does tell individuals stories in a unique way.
I’ve been on the interviewee side of podcasts a few times, and I’m planning another one this week with Scott Nesbitt and Aaron Davis of DMN Communications. But it was neat to be an assistant to podcast production even if only for a few months.
Reasons for moving towards a conversation, towards collaboration, towards the community
What if your user’s guide had to read like an Instant Messaging, or IM conversation - quick, real-time questions, fast answers, and tailored to nearly every potential customer situation? Harry Miller from Microsoft pondered this very question in a podcast in the mid-2000s.
Sometimes users expect precise answers from their user guide. When you work with a product, you want to be able to impress people with your knowledge and efficiency. Or, you have a particular aversion to truly learning a product that you have to use to do your job, but you only use the product once every other month to do a specific (perhaps boring) task. Your manual does not talk back to your users in either situation just yet. But the person who reads the entire manual cover to cover will have conversations in turn with the people to look to him as the expert in the office.
Even if your documentation system can’t “talk back” to your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well, play at home with more fun, or learn something new in a classroom setting. I have ideas for how you can think about documentation and user assistance in a conversational way, perhaps with the help of some social media technology applications.
Now, there are plenty of good reasons for technical writers to avoid actual conversation with customers. We are not necessarily trained in diffusing an angry customer or in troubleshooting the product at the technical level that is necessary. But we are good at learning quickly and applying technology to solve problems. These are not skills left only to the young talkative type, the technically savvy geek, or the extreme extrovert.
You might think that the term social media or a buzzword comes up is that the technology is meant for young people only, or that you have to have a lot of spare time to appreciate things like social bookmarking or Second Life. But the reality is that communicators are already skilled with many of these technologies. We just have to be able to apply them to individual situations and build a business case if necessary.
BookSprint Laps
What is a continuation of a BookSprint called? I’m not sure what to call it, nor do I know which metaphors might fit, but there has been some additional energy emanating from the Austin-based OLPC BookSprint. In the week following the FLOSS Manuals BookSprint, OLPC has energized interns and staff members to continue refining existing chapters and adding new chapters also. As maintainer of the doc, I’ve been watching the changes on notifications and will make my own minor edits, but for the most part I’m just watching in delight at the outpouring of content. Another win for us writers is that the manuals will be remixed, output as HTML, and included on the XO laptop itself for deployments. My sincere hope is that good documentation will prove helpful to the support gang who work so hard on
I’m also completely tickled by the emails of encouragement and thanks coming from all parts of the community. Here are some excerpts from an email from David Farning, an awesome Sugar Labs community guy who I know I can learn a lot more from:
I realized this was not just a couple of programmers trying to throw
together a wiki as I watched Janet Swisher intensely studying the XO’s
battery. Turns out she trying to determine if the installing the
battery section could be misread. From my experience, a programmer
would have said, “If they can’t figure out how to put the battery in,
what’s the point of a fine manual.”David Cramer, a tech writer at Motive, the company that hosted the
event, provided a excellent takeaway on tech writing. ’When I write, I
write for one person. Usually, one person reads what I write. The rest
of the department just asks him….’ Very on point for SL (Sugar Labs) and OLPC.
With our limited resources, we can’t afford to target a broad audience.
But, can afford to target ‘that one guy’ who can spread our message.
Technical Communication bloggers have also caught on to the uniqueness and excitement of this community documentation site, FLOSS Manuals. Tom Johnson, Heidi Hanson, and Charles Jeter talk about it around the 7:30 mark of this podcast:
Quotes from the audio -
about the site “I’ve never seen anything quite like it…”
about the BookSprint “an amazing collaborative community type of event…”
about the FLOSS Manuals community “the social organization of it is going to give it it’s best foot forward…”
Adam Hyde has done an excellent round up of blog entries that talk about FLOSS Manuals. He took a picture of these covers of the books. They look so good and it’s so satisfying to see a book deliverable so quickly.
Additional excitement for this week centers around translation of the content. FLOSS Manuals has a side-by-side translation interface and all of the wiki interface is also in the language of the translators choice. See fa.flossmanuals.net to see the Farsi FLOSS Manuals.
Where do you start conversations?
The biggest mistake is believing there is one right way to listen, to talk, to have a conversation - or a relationship. - Deborah Tannen
There are new social media tools being invented all the time, and traditional websites are also finding ways to incorporate tagging, sharing, and other collaboration helpers in their content.
I believe that a conversation doesn’t have to be a direct connection between technical writer and customer. I want to also think about how you help customers connect with each other.
So, let’s discuss ideas for starting conversations. You probably want to study the categories of contributions that you want to ensure match up with your role in your company.
Matching up your strengths and experience to the conversations helps to avoid stepping on toes or stumbling into conversations where you do not have the tools, background, or correct messaging to know how to deal with the situation correctly.
There are plenty of skill sets that are valuable in traditional user assistance deliverables that are easily transferable to a movement towards social network integration for user assistance. These skills include:
- excellent communication
- clear writing
- good design
- up front planning
- keywords and indexing (tagging)
- understanding of semantic markup
What other skills do you think writers bring to the conversation buffet that is the social web?
BookSprint - results!
What a week it was. I’m tired but very proud of what we accomplished.
We wrote seven manuals for One Laptop per Child in a week: one for Sugar, the operating system, one the XO, which is the hardware for all of the deployments for One Laptop per Child, and manuals for five Activities: Browse, Terminal, Write, Chat, and Record. I think our PDF page count is over 200 pages!
Cover pages from the seven manuals we completed.
Results - the XO Manual is available (56 pages) and the Sugar Manual is available (132 pages). While the XO manual still has some missing images (screenshots and such), and I’d like to keep expanding the “Beyond Activities” chapter in the Sugar manual, we met the goals of the Sprint. Documentation never feels “done,” does it? Updated to add: the images are in the networking chapter of the XO manual, yuh!
Here’s how the week went. Sunday afternoon, we met at my employers for about 2-3 hours to plan out the outlines for all the books and make sure the scope was appropriate for the writers we had. I had an online discussion the prior week on the OLPC Library list, where content is discussed, to get buy-in from the community on the scope of the books and the audience for the books. By focusing the audience, we helped set scope, and by asking questions about scope and getting feedback, we could further narrow down the outlines for the manuals.
Sunday night we had a nice social event with the XO Austin user’s group at Mozart’s coffee house and finished up the night at Hula Hut for a nice dinner and drinks discussion. This type of informal socializing helped us get to know each other.
In a great conference room at Motive on Monday, Tuesday, and Wednesday we wrote all day, as if it were a work day. Tuesday night we had a cookout at the hotel. We intended to have some more rest and relaxation Wednesday afternoon, but then decided to push it to the evening to keep the writing momentum going forward, but we all were tired enough to opt out of a 10 o’clock movie at the Alamo Draft House.
Thursday was spent as if we were in the last lap of the sprint, writing and finishing furiously, and Friday we spent doing cleanup in order to create all seven PDFs by the end of the day.
I’ll have a lot more to say about the BookSprint in the coming weeks and months, because I believe in this model for free documentation and I am so in awe of FLOSS Manual’s wiki toolset and remix capabilities. Updated to add: thanks to Adam Hyde, Aleksandar Erkalovic (aco), who was updating while we sprinted, and Lotte Meijer, who made the awesome covers for the manuals. Your group makes up an amazing team.
In the meantime, enjoy some of my favorite pictures from the event.
Adam quite happy with the resulting PDF printouts
Walter Bender of Sugar Labs, and Adam of FLOSS Manuals writing the day away
FLOSS Manuals' wiki interface even works in the Browse Activity on an XO laptop as shown in this screenshot!
What’s next? As the maintainer of the doc set in FLOSS Manuals, I’m monitoring notifications on every manual we worked on. I want to continue accepting documentation requests through the Comment system on each chapter of the manuals in FLOSS Manuals. I hope that the participants will continue to feel ownership and make updates as they see fit. We’re hoping to translate both the content and the FLOSS Manuals interface to Spanish to assist in and create efficiencies for Spanish translation of the content.
There are so many thank yous and acknowledgments for the hard work this week - I hope I have adequately personally thanked all who participated in the planning leading up to the sprint as well as the many people who participated in the sprint itself. I’m bursting with pride in the community effort here and hoping to keep the momentum going in an even, sustainable pace. For the next few weeks I need to get my energy back from such a “sprint” effort, but I’m very proud of our results.
XO BookSprint instructions
Adam Hyde of FLOSS Manuals wrote up these instructions for how to get involved with the BookSprint going on this week. I’m hoping to write blog entries that describe the planning sessions and surrounding practical advice for this type of writing sprint, but I wanted to let my readers know the basic overview of how to participate this very week. Thanks Adam Hyde! Adam’s presenting at DocTrain East this fall, if you’d like to know more about FLOSS Manuals and the remixing the system enables.
XO BookSprint
This week in Austin, Texas a team of writers are gathering together to immerse themselves in a one week intensive documentation jam.
The purpose of the Book Sprint is to produce documentation in 1 week to support the forthcoming 2008 roll-out off the OLPC G1G1. The team in Austin consists of members of FLOSS Manuals (Adam Hyde, Anne Gentle), OLPC (Adam Holt), Sugar (David Farning, Walter Bender), and the Austin XO Users Group, and YOU! We have set up the online tools so you too can contribute! To make a contribution please do the following :
1. Register
To contribute to the documentation you can register at FLOSS Manuals :
http://en.flossmanuals.net/register
2. Contribute!
There are several manuals planned to be finished by the end of the week
(August 29) including a Sugar manual, an XO manual, and 5 Sugar
Activities manuals. You can see the structure of the manuals here:
Sugar :
http://en.flossmanuals.net/bin/view/Sugar
XO (OLPC Hardware) :
http://en.flossmanuals.net/bin/view/XO
Sugar Activities :
http://en.flossmanuals.net/bin/view/Browse
http://en.flossmanuals.net/bin/view/Chat
http://en.flossmanuals.net/bin/view/Record
http://en.flossmanuals.net/bin/view/Terminal
http://en.flossmanuals.net/bin/view/Write
To contribute you must register and then select a manual and a chapter
to work on. if it is not marked ‘complete’ then press the edit button!
Its as simple as that.
Contributions can include cleaning up layout, spell checking, adding
images, proof reading, or taking responsibility for writing one of more
chapters. You don’t have to be a technical writer or a super geek, you
just need to know how to write.
If you need to ask us questions about how to contribute then join the
chat room listed above and ask us! We look forward to your contribution!
For more information on using FLOSS Manuals you may also wish to read
our manual :
http://en.flossmanuals.net/FLOSSManuals
3. Chat
Its a good idea to talk with us so we can help co-ordinate all
contributions. We have a chat room for this using Internet Relay Chat
(IRC). If you know how to use IRC you can connect to the following :
server : irc.freenode.net
channel : #olpc-content
If you do not know how to use IRC then visit the following web based
chat software in your browser :
http://irc.flossmanuals.net/
Information on how to use this web based chat software is here :
http://en.flossmanuals.net/FLOSSManuals/IRC
