You know how all these bizarre yet entertaining Twitter accounts keep popping up? The character-based Mad Men account, @BettyDraper the one quoting his hilarious father (with the not-censored four-letter-word-in-the-title), the FakeSteveJobs account, and how about this insane spam one, @horse_ebooks, told in the Ballad of @Horse_ebooks? Best quote in that article, “The reason it hasn’t been shut down yet is the same reason it’s so hilariously terrible at its job: It doesn’t bother anyone who doesn’t want to be bothered.” I’m sure I don’t have to tell at least half of my readers about the Fake AP style book Twitter parody account. It’s sheer awesomeness.

I have a new fake Twitter account idea. It’s inspired from The Information: A History, A Theory, A Flood
by James Gleick, describing the era of the telegraph, where you were charged by the character. Yet people still wanted a sense of efficiency and value from their telegraph messages.

How about this entertaining Twitter account idea – a Twitter account entirely written in a code that you need an old telegraph code book in order to understand?

Apparently people in the 1880s wanted to be sure the receiver of the message understands manners and respect. One of the subtitles of “Bloomer’s Commercial Cryptograph” states “By the use of this work, business communications of whatever nature may be telegraphed with secrecy and economy.”

This book, Arnold’s Telegraph Codes, ensures the use of “Yes sir” and “No sir” throughout.

It would be a fun cipher each day or week, to figure out the contents of the message. Pretty sure it wouldn’t be guaranteed to be secret nor economic, but I bet we could ensure the use of Yes, sir, and No, sir.

Yes, these are the sorts of ideas I have about Twitter after using it for five years. What’s fun to me? Ciphers, information, history, and Twitter.

“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

I’m at the OpenStack Design Summit this week, and one of the OpenStack companies here, Piston Computing, created a pen that contains a scroll inside.

When you open the scroll, you can see all the commands available for the “nova” client, which is how you send commands to the OpenStack Compute API at the command line. Clever!

I’m reading new thinking from Adam Hyde, FLOSS Manuals founder, in a new book titled “A Webpage is a Book” at http://www.booki.cc/a-webpage-is-a-book/_edit/. I found the gem of a quote above in the section on collaboration. He is re-writing his book about book sprints in this new tome. I knew he had been refining his thinking after running 30 book sprints over the last five years, so I look forward to hearing his new perspectives as he shifts from “it’s editorial” to “it’s ease of production, collaboration, and reuse.”

The best motivation to collaborate on writing a book is a desire for the book to exist. To quote Antoine de Saint-Exupery:

“If you want to build a ship, don’t drum up people together to collect wood and don’t assign them tasks and work, but rather teach them to long for the endless immensity of the sea.”

My current thinking about how to get collaborative writers to long for the endless immensity of the sea, the journey from uncoupled thoughts and notes to a knowledge transfer device, is threefold:

1. Make your writing events fun and relaxing, like a writer’s retreat. The tool should disappear into the background while you just write productively. They desire for the book to be a part of their lives.
2. Give the writing group plenty of reputation building – teach them to long for the recognition that being an author on the deliverable will bring. They desire for their writing to be recognized.
3. Recruit people who already practice reciprocity – they get a kick out of being helpful. They know others helped them. They want to help and have been helped. They desire for their writing to be helpful.

Of course it’s not really this simple, but it is calming and inspiring to think of riding ocean waves to explore collaborative authoring. Holding a seashell to my ear now… ahh.

What 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.

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.

http://www.sourcefabric.org

This is fun. Fedora has “beat writers” which harken to journalists tracking a story. Each beat is a section in the release notes. I found it while poking around on the Fedora wiki pages that describe how they do documentation. See fedoraproject.org/wiki/Documentation_Beats.

I like this approach for a few reasons. One is that the term “beat” seems fresh. While I did have to look for the definition of “beat writer,” I had a notion in the back of my mind and it turned out to be correct. My initial reaction was, oh, it’s like a journalist chasing down a story, or beat reporting, being assigned to a regular route.

The second strength I see in this approach is that you can divide writing tasks and track progress. Having a “beat” assignment also matches knowledge areas to experts in that area.

Assigning someone to a “beat” also means they’ll try to uncover a story. More software documentation could use story telling. Try to tell the stories your users tell you – or better yet, let them tell their story. Curate these from blog entries or chase the story down yourself with interviews.

We’ve probably used this type of approach for ages in enterprise documentation, but this strikes me as a particular good way to parcel out work in a collaborative environment while still maintaining a high quality outcome.People are naturally drawn to their interests, and assigning them writing tasks based on areas of interest is a great method for making community documentation fun and engaging.

Which statement is true:

“PDFs are like cement.”

or

“Gentlemen prefer PDF.”

Turns out both are true! See my recent OpenStack blog entry, Hacking on Ebooks, for more context and attributions for those statements.

We recently held a hackathon which I blogged about earlier to discuss the prep work for creating epub from DocBook XML source for the OpenStack and Rackspace manuals. We had a very successful day of hacking on 11/11/11. A team of about seven writers, testers, and developers worked all day to try to make epub files. And sure enough, we did it!

Our list of bugs matches up with what others have noted about difficulties making ebooks, such as sizing images properly and enabling tables that scale when zooming in or out or being displayed on a small smartphone or a larger tablet screen. Turns out, many “pro” epub creators turn all the tables into images to avoid the sizing problem. We also noticed the problem with mobi output putting a new line for each list item, and I haven’t gotten the fix working yet. We’re starting with the OpenStack Starter Guide available as an epub download and automated outputting epub for that book. We’re checking out the downloads to see whether there’s interest and we’ll go from there!

This Friday, on 11/11/11, the Austin Rackspace office is holding a Hackathon. The projects range from “fix the arcade game” to “install notification system to indicate availability of the men’s room” to my pet hack project, “create epub output for Rackspace and OpenStack manuals.”

Here’s a short introduction about making epubs from the FLOSS Manuals book, E-Book Enlightenment.

Of all the formats for e-books only EPUB combines small file sizes with the ability to do formatted text and illustrations. An EPUB is like a website contained in a Zip file, with a Table of Contents attached. It is also in one important way different from a website. A website is made with HTML (usually) but an EPUB is made with XHTML.

The difference is small but crucial. HTML is meant to be forgiving. If you make a web page you can leave out some tags, fail to close tags, or close tags in a different order than you opened them in. A web browser is supposed to forgive that, as much as possible. XHTML, on the other hand, is like HTML that is not forgiving. You can’t leave out a tag or put in a tag where the XHTML browser does not expect it. If an XHTML browser discovers an error in your page it can simply refuse to display it.

The end result is that an XHTML browser is easier to make than an HTML browser. A lot easier. It does put a burden on the e-book author to get his tags right, but in practice you’ll never create an XHTML file by hand.

With automation in mind, we’re going to use our existing toolchain to make the epub. Earlier this year, Robert Nagle, a tech writer in Houston, wrote up his findings about Docbook and epub. He writes for the Teleread website. What’s interesting to me is that he wrote up this blog post last year (11/7/10) about his findings while making epub from DocBook source and this past September said his next priority is moving his workflow to Oxygen + Ant + DocBook. David Cramer, our Doc Build Developer, has briefly tested the Maven-based toolchain by simply adding the goal generate-epub to a pom.xml file and building. That method did not copy over images. Then he tried building as part of the clouddocs plugin and received an error. We’ll start our debugging with the toolset, but we’ll also need debugging of our DocBook source as well.

Most of the “success” of the hack fest will be having fun and not sweating the small stuff. To me, we can call it done when we have epub examples for one OpenStack book and one Rackspace book that you can page through and read on a plane. Images should behave within reason, tables should be readable, and notes should be designated as such. Beyond those criteria, we’re exceeding expectations.

In case you’re curious about our tool chain for OpenStack docs, I have instructions on the OpenStack wiki. If you’re on a Mac or Linux machine, here are the quick steps for getting started with the tool chain for the openstack-manuals project:

1. First install the Apache Maven project.
With Macports already installed on a Mac, you can do this:

sudo port install maven2
or on Ubuntu

sudo apt-get install maven2

2. Install Git by referring to Mac or Linux instructions.

3. Get (git it? Ha!) and then build the docs with these commands:

git clone https://github.com/openstack/compute-api.git
cd compute-api/openstack-compute-api-1.1
mvn clean generate-sources

You will see a /target directory containing HTML and PDF output. Perhaps after Friday, you’ll also see epub output, who knows? While Friday’s Hackathon is for Austin Rackers, I’m happy to share our experiences here. Here’s hoping the OpenStack community will benefit from our hacking.

At Rackspace we get these great email threads due to an email list designated for “fun” at each core location. One of these such email threads started with a guy asking if any other guys do sewing – and wondering where he could learn to sew on projects that were gender-neutral? He wasn’t going to make a purse, after all, he needed to hem pants and wondered about suit making. The best part of the thread was when he invented a term, fabric welding, to see if he could get more interest that way. It was a fabulous turn of phrase, though I don’t know if it garnered more interest.

I was so tickled by the term “fabric welding” that I had to blog about it during this week, Halloween week, the week of costumes. What turn of phrase have you heard lately? My second-grader read the phrase “love to hate” the other day and it made him chuckle. Here he is with his fabric-welded Link hat, fabric-welded elf ears, wooden Deku shield, ready for an adventure.

Happy Halloweenie!