Archive for the ‘tools’ Category:
Does designing content for scanning devalue the content?
I just read a great post by Rajesh Setty on the Lateral Action blog called 9 Ways People Respond to Your Content Online. Maybe it’s because I’m in the final countdown before my book is permanently affixed to the pulp of dead trees, or maybe it’s because I’m looking at online user assistance tools to see how they can enable conversational documentation, but it struck me that user assistance gets stuck in that first low value category often. Here’s the excellent visual that shows how return on investment increases as the response to the content becomes more and more spreadable, actionable, returnable, and impossible to ignore.
We are told as writers to make our online help scannable, that people don’t linger on it, they just want to find the answer, get in, get out, get on with their work. With the classic online help tools available, we rarely break into that second tier where readers can stop, save (as in social bookmarking), and shift their thinking based on the content.
And the final tier, send, spread, and subscribe, are actions not yet available in a classic help authoring tool. The “send” action can be via email only, and most help systems have to have that type of link specially coded. Spreading a link via social networks is not yet enabled in online help systems that I know of. And how many help vendors offer a subscribe or notification system?
If these response mechanisms are what your audience requires, you may have rethink your Help Authoring Tool selection and look at comment tools, blogs and wikis, and create a help system offers the features that give opportunity to leverage content and engage the readers. I believe Adobe has accomplished these goals with a hybrid approach that offers traditional online user assistance that includes the ability to “talk back” to the help writer via comments on each help topic.
I benefited from their approach this weekend in fact. I have a lot of footnotes in my book that point to relevant web pages and blog entries. I wanted to collect them into endnotes for the entire book. So I searched in the Indesign Support Center site. You can either search their Community Help or search the Indesign Online Help. The Community Help feature is in public beta according to the About page, and they are using a Google Custom Search Engine to “selectively index only the most high quality sites and resources.” I found a series of comments on the topic about footnotes that led me to a blog entry from the lead writer on blogs.adobe.com. His blog entry describes gathering footnotes into endnotes that use cross-references – apparently an old FrameMaker trick! And, to make it even more clear that a community helped this writer, he credits a forum post comment in a InDesign user forum with giving him the answer. Plus, after the blog post was published, another community member commented on the blog entry, giving him a link to the scripts that would automate the footnote to endnote process described in the blog entry. I was utterly blown away. Community documentation at work for me.
What do you think? Are the tools that cater to the needs of technical publications crowd already available? Or are technical writers going to move content to blogs and wikis due to feature demands from their readers?
Love, love, <3 The Twitter Book
Wow, just got a print copy of The Twitter Book
by Tim O’Reilly (@timoreilly) and Sarah Milstein (@SarahM, user number 21 of Twitter). Thanks go to Andy Oram, @praxagora, for referring me to it after he read a draft of my upcoming book.
The layout, form factor, full-bleed color page numbers, and color screenshots and photos (Twitpics) throughout the interior are just wonderful. This design combination makes it an excellent hand-held object, worthy of being print-based! I’ll keep this one out in my living room. But I’m kind of nerdy that way.
It has important and useful information about Twitter (www.twitter.com) and why it’s so powerful. Just thumbing through it I found two things I didn’t know about Twitter (and I’ve been on Twitter as @annegentle since early 2007.) One is, it really is a big deal that Twitter removed the setting that allowed you to customize which @username replies you saw and your followers saw. There used to be three settings in the Settings>Notices tab (page , now there are none. But Twitter reversed the original policy decision, and Read Write Web gives a graphical explanation (it’s strange enough that it needs explanation.)
The second informative tip is that for the most part, people tweet the most on Tuesday, Wednesday, and Thursday. And most people, if they don’t see your tweet in the first five minutes of you posting it, won’t see it at all. I bet that the more uptake we have desktop grouping helpers like TweetDeck, the longer that tweet click-through duration will last. But even with better grouping so that you don’t miss tweets from people you really want to read, as more and more people join Twitter, it’s harder and harder to ensure you get the information you want. So you might want to think about using TweetLater to post a slightly re-worded micropost at another time.
I have to admit, I do like Chris Brogan’s idea of using the hashtag #getoffmylawn for celebrities who use Twitter in an annoying way. But better yet, have more and more people read The Twitter Book to get better and better at their Twitter use and micropost writing.
And finally, words to live by, in Chapter 3 “Hold Great Conversations.” On Twitter or any other community and communication site, it’s not about you! The best part is about contributing to the community – make a positive impact. “…the more value you create for the community, the more value it will create for you.”
Climb collaboration levels with me in Atlanta

Photo courtesy lollaping
I finished my presentation about Climbing the Levels of Collaboration for the Collaboration Institute at the STC Summit and I’m so excited about it I can’t stand it! True confession: I was up until 1:00 AM finishing it up and uploaded it quite late.
I found this great collaboration exercise that I’ve incorporated into the session. So we’ll be drawing with Crayola markers. Maybe even collaboratively. I’m hoping for quite the Back of the Napkin experience.
This session walks through the different ways you can collaborate with your users (and co-workers) especially when wikis are enabling the collaboration. I’ll be talking about Book Sprints and FLOSS Manuals and tell stories from my experiences. I was inspired by the examples of amazing group accomplishments described in Clay Shirky’s book, Here Comes Everybody: The Power of Organizing Without Organizations. While shopping around the ideas for the talk, I emailed people and asked what they thought of this description:
Groups can take action even quicker than ever before in history thanks to tools that amplify group communications such as wikis, blogs, and instant messaging. There are three distinct levels of collaboration that a group can attain and what they accomplish directly correlates to the level of collaboration.
People I talked with definitely wanted to know best practices for wiki authoring techniques. One person even wanted to know how to incorporate user-generated content into their help system. I’ve heard that request before – such as, how could you import wiki content into Robohelp? Also, what I learned at last weeks’ talk was a high number of people wanting recommendations for wiki engines. There are over 90 to choose from on wikimatrix.org. Eep. Writers also wanted to how to organize content on a wiki. I won’t promise to have all the answers or any of the answers but I am looking forward to sharing my stories and hearing yours.
Author-it migration to version 5
Here’s a report from the acceptance testing we’ve done to go from Author-it 4.5 to 5.x.
I don’t know if anyone else had difficulty understanding the best migration strategy, but I thought I’d talk about my misunderstanding in case it helps others. At one point, we thought it might be a good idea to take only new content to 5.x, giving us a chance to test for a long time before relying on 5.x for our production. I also wasn’t sure how we were going to go from 4.5 on SQL Server 2000 to 5.x on SQL Server 2005. To get a two-server environment (4.5 and 5.x, 2000 and 2005) I thought exporting to XML would be the way to go – as long as we got all dependent objects, we should be able to start fresh by basically populating the default database. There were so many additional steps to try to export content that it turned out a wholesale upgrade of the database was a much easier route. We just had to put in an IT request to create a .bak file of the SQL Server 2000 file, then have them restore that .bak to SQL Server 2005. All our users, variables, everything came over that way and all we had to do was “open” (connect to) the SQL Server 2005 library with Administrator and the upgrade went quite quickly.
I also offer our notes from acceptance testing we did last fall. I haven’t yet logged any oddities we’ve seen but will try to do so in the coming weeks. So here goes!
Author-it 5.1 Acceptance Testing
As a preliminary test, three authors tested a SQL-Server based Author-it test database for an hour simultaneously on 8/15/08. This report contains our notes from the testing session and further discussion as we researched some of the difficulties we found.
Overall
Performance
Anne said it seems sluggish to open a topic, but Melissa found it normal.
Anne: Creating a new topic using a template is slower than 4.5.
Usability
Anne:
- Why does it use Times New Roman for all the topic titles in the Book map view? Guess it’s because of my Windows theme which uses a serif font for titles.
- Change in how to set up options: click the big A, then click Author-it Options. You’ll want to be sure to select the Auto save all open objects every n minutes on the General tab since we’re accustomed to the Auto save feature, since it was automatically enabled in 4.5.
- If you double-click the Big A, you close AIT.
- You can’t see anything on the Change Release State menu when in the Book Editor.
Daily work
This testing involves the writing and authoring aspects of Author-it.
Editing
Melissa saw no problems.
Anne:
Regular typing and over typing seems like business as usual. See links notes and style notes as well, though.
Authoring
Anne:
Creating a new topic has more clicks because of a new folder – the AuthorIT Website Manager folder. Can we get rid of that nesting somehow?
Melissa:
No problems creating a new topic, basing it on a template, and adding content.
Strange saving behavior in the book editor:
Procedure: Edit a topic in the book but don’t save your work. Move to another topic in the book. My work was saved.
Procedure: Edit a topic in the book but don’t save your work. Close the book object before moving on to another topic. My work was NOT saved. It did not give me a warning that I had unsaved work. AIT4 used to issue a warning in this situation.
Procedure: Create a new topic in a book, add content to the topic, save the topic, and close the book. When I opened the book after closing it, the topic was not in the book. However, the topic is saved in the folder that was selected when I created it. I realized afterwards that I did not click the icon to save the book as well. It did not warn me that I had unsaved work.
Lesson: Always be sure to manually save your work to the topic AND the book. You will not be warned if you are about to lose unsaved work. Melissa did find the setting changed from 4.5 to 5.1 in the Author-it Options dialog box. You’ll want to be sure to select the Auto save all open objects every n minutes on the General tab since we’re accustomed to the Auto save feature, since it was automatically enabled in 4.5.
Applying styles
Anne:
Applying no paragraph styling is a little easier, but the nested style menus with folders makes for more clicking.
Melissa:
I don’t like the paragraph and character style selection lists. After clicking the dropdown arrow and then Styles, I can’t do two things that I could in AIT4: I can’t use the up and down arrows to scroll the list. I have to click the up and down arrows on the screen. I also can’t type in a letter to jump to the style I want in the list.
I can no longer right-click a selection to change the style.
Searching for words within a book object
Anne:
Very fast for search, but replace was dogged for just 9 instances in the 2_Casual_Contact_management sub-book. And the progress bar showed 7 of 9 but then the final dialog box showed “23 replacements made.” That’s a little unnerving.
As far as I can tell, you still can’t search for certain words with styles applied and then replace with another word with no style applied.
Melissa:
Works better than it did in AIT4. In AIT4, if I used this search function more than a couple times, it would stop highlighting the words consistently. It is working consistently so far in 5.
Searching for a topic or other object within the library
Anne:
You just choose a different dropdown menu to change the scope of find and replace, which is nice. But when you choose “Look in: Library” there is no Replace All choice? And no way to “Find Next” when what was found isn’t what you were wanting to replace? Example: Search for Contacts and replace with <tContacts> in the whole Library.
Melissa:
I love that we can now search for objects within a folder. This limitation was frustrating in AIT4.
When I switch between the Folders view and the Search view, the main pane changes accordingly, as it should. In AIT4, after I searched for an object and then clicked Folders to return to that view, the search results would remain in the main pane. I would have to select a folder for the main pane to refresh. This is a good change.
Showing relationships
Anne:
Looks great to me. I like the new tab that shows “Books using this topic” in the Book Editor.
Melissa:
Works like it did in AIT4. No problems that I can see.
Importing graphics
Anne: Double-clicked a graphic in a topic in the Book Editor to change it, and AIT opened a Properties dialog for the graphic, but I’m not sure how to replace the graphic with a new one – ah ha, the menu changed. You don’t click the little triangle/circle/square icon, you click Insert or Open menus.
Melissa: No problems.
Creating sub-books (Create a technical review excerpt)
Couldn’t create a DT excerpt because the template did not get imported due to no dependencies on that DT excerpt template object, but just made a User Guide book.
Inserting variables
When creating the <pi> variable, I couldn’t choose Char – iMIS as a style. It must not have been brought over? Added that note to the list of items we’ll have to add to the database after import.
Apply release states
Anne:
None of the imported topics kept their release status.
You can only apply release states in the folder explorer view, not by right-clicking in within a book object.
Melissa:
Topic release states can not be changed in book editor view. You have to select the topic from its folder location, and then the available release states appear.
Apply template
No problems. Creating a new topic using a template seems slower than 4.5.
Create links
When I drag a topic and choose Hyperlink: Jump, it adds (|Hyperlink: Jump) to the text on the hyperlink.
Advanced work
This type of work involves publishing and other not-so-daily tasks.
Versioning (Branching topics)
Bulk object duplication-select a range and clone a whole set.
Publishing
Publishing looks to be slower, perhaps 30-50%, but we would need more content in there to fairly compare.
Anne: our later tests on 5.2 found probably speeding up of publishing from 4.5 to 5.2.
Automated building
Promising aspects of 5.x: publishing profiles, variable variants, which offer conditional content control: allows maintaining multiple release versions in one library.
List of what must be added to the database after importing content
- Users and their roles
- Variables
- Any style that is not used by content, such as Char – iMIS
- Release states
- Folder permissions
- DT Excerpt books and other special books not brought over after importing
What we’ve found since doing a content import is that it’ll work well for us to migrate content to a database rather than imorting content.
What is Anne Gentle up to?
I finally feel some energy returning after my eye injury about a month ago, although my right eye remains dilated which still means that side is a bit out-of-focus and I don’t like driving at night. I feel like I need to give a status update or some such. So here goes.
Winter Camp
With luck my eye should be just fine in time for a big event coming up: Winter Camp 09 the first week of March. I’ll be representing and working for FLOSS Manuals at this event, held in Amsterdam. From the description, it will be an amazing week:
Network Cultures Winter Camp will be a mix of presentations and work spaces with an emphasis on getting things done. It will be a four-day program of work spaces and plenary presentations, in which a dozen networks (each of which has 5-15 people) can work on their specific current topics.
The format was inspired by a cardboard box art installation that activates a temporary warehouse of contemporary knowledge from what I can gather from a translation of the page, Re-fitting ideas. Come on, that’s incredible. I am so thrilled to be a part of it. And I know it’s going to be a week of hard work.
Preschool website completed, using Wordpress 2.7
We’ve also finished the preschool website I mentioned in my interview with Michael Silverman of Duo Consulting. We used WordPress hosted at Midas Networks. I recorded some screencasts with Jing to show other parent volunteers how to edit content and work with images. All the photos on the site were taken by parents so it’s quite the “do-it-yourself” website. I am hoping that Wordpress 2.7 will be easy enough for even those in our volunteer and staff group who are not technically savvy but still give us the growth towards more content creators that we have in our goals for the site.
FLOSS Manuals and OLPC
We’ve sold over 200 copies of the OLPC Laptop Users Guide on Lulu.com, and Adam Hyde gave a copy of one of FLOSS Manuals’ books to Bob Young, the CEO of Lulu, while they were at the O’Reilly Tools of Change conference. Impressive. I still plan to make the Sugar Users Guide better. Adam Hyde and I are working on a book about how to run a Book Sprint in FLOSS Manuals, naturally, and we would welcome additional contributors.
DITA and Web 2.0
I’ve been approached to help put a public face on standards for DITA and Web 2.0 projects such as DITA for wikis (an example is Lisa Dyer’s DITA2Wiki project on SourceForge) and DITA for blogs (another example is DITA to Wordpress or DITA and microformats).
STC Intercom Editorial Advisory Panel
I’ve been pretty impressed with the STC Intercom issues in 2009 so far, but I wrote one of the articles so perhaps my judgement would be playing favorites. I would like to gather feedback from STC members and non-members who read the articles – how’s the content grabbing you this year?
Author-it 5.2
It looks as though 5.2 is the version of Author-it that will allow us to upgrade from 4.5. Our content just wouldn’t publish adequately (Word or HTML) on 5.0 or 5.1, but now that 5.2 is released, fingers crossed, we’ll be moving to 5.2 soon. I should write a blog post about some of our testing on our 20,000+ object database. I’m getting used to the Ribbon Bar as I continue to work in Word 2007, and Author-it’s 5.x interface feels a lot like Word 2007.
Writing a book, do tell me what you want to know
Last but certainly not least, I’m working with a professional editor to try to finalize my book about documentation as conversation that examines the power of social media for writing projects. It walks through the myriad of possibilities of different types of social media tools and analyzes how writers and communities are using these tools for technical documentation. Look for it this spring!
Author-it and MadCap Flare comparison
I’ve had more than a few questions asking for a review of Author-it or MadCap Flare or a comparison of both. So I decided to do some homework. Initially, I wasn’t sure why they are categorized together. Is it due to the price point? Or is it due to the single-sourcing all-in-one software package aspect? I suspect it’s the latter since the former seems more disparate lately.
Let’s examine the single-sourcing aspects.
Both MadCap Flare and Author-it only work on Windows for authoring (but both offer cross-platform and cross-browser output).
Both MadCap Flare and Author-it output to printed and online formats. These formats and the way they arrive at the output offer some differences, as seen in the “publishing aspects” section below.
Both MadCap Flare and Author-it have a single place to store source.
Both are sourced in databases. The single source for MadCap Flare is in a flat folder structure with XML files. MySQL database. The single source for Author-it is in either a free Jet/MSDE/SQL Express database for up to 4 MGB of content, or SQL Server.
Author-it only imports Word documents. Flare imports both Word and FrameMaker documents as projects.
What are the publishing aspects?
Author-it uses Word templates for all printed page layout. If you’re well-versed and experienced in Word for page layout, this product works for you.
Author-it uses CSS for HTML layout, but some layout and graphics are controlled in different areas. I had to uncover the locations for each graphic and CSS area recently while customizing the HTML output for the One Laptop Per Child project. In my experience the HTML layout was all over the place. From templates to stored objects to files stored locally to certain aspects changed within a dialog box on a template, I felt like the online layout was a bit scattered.
Here are links to their Knowledge Center articles that were helpful: Customizing Related Topics in HTML, Adding a Customized HTML Template, and Using a Customized HTML Frameset. I muddled through somehow, and I don’t have a good comparison for MadCap Flare’s HTML output.
Keith Soltys has a nice Review of MadCap Flare from summer of 2007 that shed some light onto the publishing and he speaks highly of the layout rendering nicely in both FireFox and Internet Explorer. It’s interesting, though, that he’s evaluating Author-it as well, so I guess these two products are often compared side-by-side.
Apparently MadCap Flare uses CSS for all layout aspects including print. The new Blaze announcement offers a non-Frame and non-Word reliance for actual PDF or print output. The reliance on CSS (Word’s interpretation of CSS has its limits) may have forced MadCap to create Blaze. Anyone else think you should wait for the CSS 3.0 specification before really nit-picky print layouts can be accomplished? Or is CSS ready for this level of design? I know with the OLPC project, we’d love CSS layout for really nice ebooks, so maybe MadCap is onto something with CSS for print layout.
I’ve written up this comparison because many people have asked me for it, but I know it’s lacking. Please, feel free to fill in the gaps that this post has so that others may fairly evaluate each tool in their environment.
I had an email conversation with Kai many months ago, who was a good sport with all of my questions regarding the content and priorities with that content. He realized, though, that Author-it was probably eliminated due to its use of SQL Server – they wanted a MySQL database container for their content. So I figured that MadCap was their final answer. It is so interesting how the final decision can be dictated by the underlying system requirements. One of the commenters on Gordon Mclean’s post, Why AuthorIT? (sic, they’re now Author-it) was seeking a similar authoring tool but on a Mac platform.
Sorry Kai for dropping the conversation for so long. But please do share your experience with the tools since then.
Author-it Table Of Contents expansion
My co-worker Melissa Burpo (yep, I interviewed her before she was my co-worker) has solved a nagging problem with the HTML output from Author-it. The Table of Contents would always lose your place when you expanded one of the TOC items – instead of “keeping your place” vertically, it scrolls your view to the top of the frame. We have a long table of contents and this particular implementation got a lot of complaints.
Rather than shorten our Table of Contents (I would guess that’s what most shops have done), Melissa used Javascript to capture the scroll location, save the location using a cookie, and then reload the scroll location after you expand or contract the Table of Contents.
She’s allowing me to publish her solution here – let us know if you find it useful! You can see it in action at docs.imis.com.
Inserting code into your Author-it Table of Contents
Download the toc_scroll.js file supplied here and save it to your HTML Templates directory, such as C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.
Open the toc_template.htm file supplied with your Author-it installation in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.
In the <head> area, insert a pointer to the toc_scroll.js file using this code:
![]()
In the next few lines of the toc_template.htm file, give the starting point for the scrolling to load.

Modify your book so that it includes the new toc_scroll.js file and the new toc_template.htm file.
Publish your book using these modifications.
We’ve tried it on Windows XP and Vista, IE 7 and 6 and Firefox 2 and 3. Let us know your thoughts on this “fix” for a scrolling annoyance, and if you use it, give a hollah!
Adobe AIR for an interactive children’s story book
Storybook Anytime is a Flash and Adobe AIR website for kids to have their own stories in a library. It’s a great example of Adobe AIR, a technology I’m curious about for online help use. Here’s a few screenshots of the website:


Plus, the entire library is free to pre-schools, grade schools, and public libraries. I’ll have to investigate this for our preschool. We recently installed new Dell computers for the staff and teachers and for classrooms for kids age three and up. That project took up a lot of my blogging time over the holidays but it was well worth it!
How to create a photo mosaic – and print it out as a poster
I wanted to share a fun photo mosaic tip. Let’s say you wanted to decorate your office door using just your computer, the office printer, white 8.5×11 office printer paper, and the digital photos (especially screenshots!) you have stored on your computer.
Use a photo mosaic program called Andrea Mosaic and then print a giant mosaic tiled on separate pieces of regular paper. Here’s a link to the photo mosaic software that’s a free download: Andrea Mosaic, and then to print out on multiple pages, use Posteriza. Here’s what’s on my door this holiday season:

How do you develop a strategic website?
My son’s preschool has decided it needs a new website. Parents and board members want an online presence that has more interaction, dynamic logins, and password-protected content. We have goals! Elementary and private schools have followed many paths to achieving their web presence including an all-parent volunteer web staff to hiring freelance web designers to $30/month services.
I wondered how these services differed from what a firm like Duo Consulting did to develop an organization’s website. So I interviewed Duo Consulting CEO and visionary, Michael Silverman. I quickly recognized that Duo’s web content strategies for businesses far outpace my preschool’s relatively static content needs. But what I also learned was that the goals of websites for many business models are often similar.
Its All About Content
What Michael told me is that websites that have a lot of changing content represent a breed of website. These may be content publishers or transactional websites. But the universal feature is that they all experience a challenge sharing their copious information online. Professional service firms, like law and accounting firms, have a lot of intellectual property that they publish on their websites. Universities, colleges and other higher education clients market themselves with their content.
Transactional websites, essentially online stores, receive considerable visibility in media coverage of the Internet. But helping organizations publish authoritative and informative content that helps them achieve their business objectives is a more challenging goal. Michael said one thing they’ve learned is that Search Engine Optimization and other traffic generation strategies is only a first step. You also need a highly usable and easily navigated site so that once visitors arrive at a site, they have a meaningful business experience.
Experience Managing Content Produces Client Dividends
With a focus on helping its client manage content, Duo has clients in multiple market including newspaper and magazines, professional services and non-profit organizations. Having experience with these industries permits Duo to more effectively scope a project when they’ve done one like it before. And they can bring best practices to the client for their particular type of business and online presence.
Having content management experience helped Duo to be chosen by the Christian Science Monitor to implement their Web-first strategy. The Christian Science Monitor intends to convert their content from a print-based periodical to a weekly web publication system. Duo has the experience with online periodicals to design and build the online interaction that they will need to be successful with this new direction for their content.
Wikis and Social Media Serve Non-Profit Organizations
Non-profits, especially those that do online fundraising, need an evolving strategic web presence to accomplish their business goals. According to Michael one of the trends Duo is seeing with non-profits and web content is a strong interest in using wikis. Volunteers collaborate using wikis when they’re on committees, they share files and communicate with the wiki. They’re also seeing much more uptake of social networking in a website’s strategy, adding functionality for websites so that people can easily form groups for discussion or common interests or other tasks. He mentioned Google Friend Connect which has been in private beta until now. It lets you add social features to your website, and indicates Google is ready to compete outright with Facebook.
When You’re Thinking About a Website Think About…
Michael said he’d like to leave people with two suggestions for strong web content – one is that a web site should have a “job description” just like any employee does. They ask people, what do you want your website to do, and how do you measure its success at doing those tasks? You may not want to set specific numbers to reach within a particular time frame, but you do want to see continual improvement.
Along those lines, he also says that you are never really done with a website. Do not expend all your energy and resources just towards a launch of a website – ensure that you can have the sustained power to see how it’s performing, then look at improvements along the way and milestones that you want to reach with your content.
Subscribe to RSS

Anne Gentle is the author of 
