Subscribe to RSS
Archive for the ‘Uncategorized’ Category:
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.
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.
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.
A summer experiment with Google AdWords
This summer I had fun writing an article about writing AdWords ads - and seeing if I could use the AdWords network to sell my presentation audio and slide deck, A Technical Writer’s Role in Web 2.0: Wiki-fy Your Doc Set.
The article is availabe on TheContentWrangler.com site - Managing Small Content:Counting Characters. Here’s an excerpt:
As part of a summer experiment, I decided to find or create an information product that I could then sell using a Google AdWords campaign. Mind you, I have no prior sales or marketing experience, and I’m sure it shows! But in an age when one can experiment for less money than the cost of a few business lunches, I thought I’d see what I could set up. I’ll share my findings with you, and I’d love to hear your feedback on this approach.
Author-it and indexing
If you do a search on the Author-it Yahoo Group about indexing, you will find a wide array of knowledge about some of the best ways to set up indexes especially when you have multiple deliverables.
If you do a Google search for Author-it and indexing, you find out about the Author-it Xtend™ Indexing Service, but that’s not what this post is about. This post is about indexes on sub-books, the kind that give you page numbers, or links to HTML help files in an Index tab.
Indexing is as much art as craft as this Future of Indexing article states so well, and has a wonderful storied history in taxonomy, metadata (or metacrap as Cory Doctorow so eloquently pens), and the Dublin Core metadata model. Not exactly a simple endeavor, to provide keywords and synonyms and figure out which terms to use as sub-entries and duplicate as primary entries.
On the Yahoo Group, Sue Heim has suggestions about using index objects within index objects, nesting the indexes within one main index. Author-it is smart enough to merge multiple index entries no matter what the output. Here’s the general setup for an example set of two books, one for Windows, one for UNIX:
Main index object built with the two index objects listed below plus any index entries that are common to each book, and then also:
- index object for Windows-based book containing entries just for that sub-book
- index object for UNIX-based book containing entries just for that sub-book
Each book uses the main index object. This strategy sounds flat-out brilliant to me, and would certainly make for more manageable indexes (indices? But that sounds oh-so-formal and this is a blog for goodness sake.)
Author-it index object maintenance
One maintenance problem that I’ve run into and found a solution for is that sometimes index entries seem “hidden.” I’ll try to delete an index entry and Author-it tells me it’s in use somewhere, typically in this gigantic comprehensive index we’re using (because we haven’t yet implemented the cool sub-index idea). I’ll open the comprehensive index but can’t see the particular entry I want to delete because it’s a sub-entry to another entry, and it may not be named as logically as I’d like.
So, I export the comprehensive index to XML, and open the XML file in a text editor and search for the index entry object’s ID.
The Object ID is typically the second hit when you search for an Object ID because the beginning of the index has a listing of just Object IDs. You’ll be able to figure out what the primary entry is then, as this screenshot below shows.
Once you determine what the primary entry is, you can delete it in the comprehensive Index object, which then unhooks the dependency and you can delete the original Index entry object that you intended to delete. Whew! What are some of your tips and tricks for index maintenance in Author-it?
Scriptorium’s Framemaker wiki - knowledge sharing, brain dumping, and learning
Honestly, Sarah O’Keefe’s blog entry describing the new Scriptorium wiki at wiki.scriptorium.com doesn’t do the content justice - there is really, really good stuff on that wiki!
I’d love to see this wiki become a hub and community for Framemaker users whether you’re just starting out or you’ve been maintaining Frame source for years.
Hightail it over there and register for a login.
Considering that we now have this Scriptorium wiki, the WebWorks wiki, the Technical Writing wikiversity, the DITA wiki at dita.xml.org, and keycontent.org, technical writers have some nice wikis to join, contribute to, or just read. What other wiki communities are indispensable for technical writers?
Understanding the database implementation of Author-it
Author-it uses a SQL Server database to house all of the source material that make up your deliverables. You can export that database content to XML and publish to Word or HTML and other outputs, but the source is stored in a database.
For locally-run databases (meaning that Author-it and the database are on the same computer), you can use a Jet database (also known as Jet, or MSDE, or SQL Express) to store your content. Updated to add: With a Jet database, your content cannot 2 GB and the upper limit for users is 5.
For server database installations, where the content is stored on a separate database server, you can use SQL Server 7.0, SQL Server 2000, or SQL Server 2005. You can use a pre-existing SQL Server database such as one that your company uses already by simply asking for a database to be created with certain permissions already set. That configuration is what we do at ASI.
You can also install and run your own SQL Server database using SQL Express which is relatively painless to set up and the installation instructions from both Author-it and Microsoft are detailed and thorough. The limitation for this configuration is that your Author-it library cannot exceed 4 GBMB.
Here are some helpful links for researching the database aspect of Author-it:
System Requirements for Author-it
STC Intercom - Editorial Calendar progress
Thanks everyone for the great comments and feedback on our starting list of theme and article ideas for STC Intercom’s 2009 editorial calendar. I appreciate that comments are still coming in, from all around the globe. I’m enjoying the international and generational communication we’re seeing, so thanks very much!
We posted ideas and requested feedback on blogs, the STC forum, and tapped Ed Rutowski’s experience and knowledge as well as hearing results from survey data he has gathered over the years. All venues have resulted in view points and reflections that are helping us on our journey to assemble an editorial calendar for next year’s ten issues.
In the weeks since I posted that entry, the advisory panel has met twice. In between the two meetings, we performed what is called a card sort using the web application at websort.net. I thought I’d share our process with you, since I found it fascinating, but also because the card sort was extremely helpful so that we could narrow down and focus the ideas from 50+ to just 10.
Websort is a Web-based card sorting tool, and the site’s intent is to help web designers improve the organization of their site. Panelist Rhonda Bracey had used it previously and thought it would be a good match for our needs. Great thinking, Rhonda!
To create our study, I used a list of keywords created from our brainstorming and invitations to the larger community to give their feedback. I had stored the keywords in a Google Spreadsheet, with one column for the keywords, and a second column for a more detailed description of what the originator meant by that idea or concept. I was able to copy and paste the keywords into the sorting tool, and then create tooltips for participants to see the longer description when they hoovered their mouse over the keyword.
Next, I sent the invitation to participate to the editorial advisory panel using the WebSort tool and the list of email addresses. Whenever a participant completed the study, I could use an RSS feed to be notified. It took me about 45 minutes to complete the study myself.
Once everyone had done the sort, I could view the results and analyze them in different ways. One analysis is called a tree view, which I sent to everyone in a PDF file that you can download. The groupings are bunched as if in a tournament bracket, with groups colored red or blue, and it offers a visual representation of how the participants grouped things in common, although the names of their groupings do not appear. You download the tree words list separately.
You can download a spreadsheet analysis tool after the study is complete, and then download and an Excel macro that takes the tree words list and compares it with each participant’s list and groupings. It produces a set of frequency tables for each item, containing a list of the groups in which that item was placed across all the participants.
Before our second meeting, I sent out the tree view PDF file and the spreadsheet with the macro run on the data. During our meeting, we then discussed the results and analysis and seven topics were clearly indicated. Our job then was to ensure that we had three theme-worthy categories and also to make sure that no topic slipped through the cracks or was ignored completely.
We discussed the difficulty in choosing a theme that will have the right content so that any issue of STC Intercom has something relevant to nearly all members, despite knowing that technical communication contains a diverse set of jobs, tool sets, and career paths. Our hope is to produce a set of themes that are relevant and that we’re realistic about recruiting writers for the articles.
We’re still working on the final list and I’ll be sure to share it. STC Intercom’s editor, Ed Rutkowski, is leaving at the end of the month, and we’ll have our list ready for the new editor. Ed has served the Society for eight years and we’ll miss him. He has been great to work with - so best wishes to Ed at his new magazine editor position! If you know a qualified applicant, and STC members are encouraged to apply, review the job description and follow the instructions in the announcement linked from the STC home page.
