Monthly Archives: April 2009

techpubs wiki

More technical documentation wikis

wikimart

Photo courtesy cogdog on flickr

I’ve been needing to update my list of wikis used for technical documentation, to see if the list is growing. Here are a few more technical information wikis. They seem to lean towards the programmer audience and might be used for a repository storage (of code samples).

SugarCRM Wiki

Knoppix wiki (zero to Linux in Five Minutes)

Ajax patterns (repository for Ajax programmers)

SQL Lite

Microformats wiki

From the blog entry “12 popular wikis that actually work” I harvested these technical topic wikis as well:

Mozillazine Knowledge Base (What a wealth of good practices in wiki writing and content maintenance. Check out their Knowledge Base changes page.)

Opera Browser and Internet Suite wiki

Game Programming wiki

I also have to mention the original, WikiWikiWeb, as a wiki to click through to every once in a while for ideas and a reminder of the original simplicity of wikis.

In other wiki-related news, the PBwiki site has changed their name to PBworks and Stewart Mader had the scoop in his blog entry today, “PBwiki Becomes PBworks; Launches Edition for Law Firms.” I find it interesting that they’ve removed the word wiki. Google Sites did something similar when they acquired JotSpot – they didn’t name it Google Wiki even though collaborative authoring was at the heart of JotSpot’s sweet spot.

And Google Knol, while similar to wiki, is trying a somewhat anti-wiki content model in that multiple articles can exist for the same topic and supposedly the best articles rise to the top to gain the most attention. But Ars Technica’s Nate Anderson points out that traffic is disappointing six months after the launch of Google Knol.

What are some of your favorite technical wikis? I’d love to hear about them.

Climb collaboration levels with me in Atlanta

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

Gather ’round, Wikify your Doc Set slides now available

I had a great time talking to the New York Metro STC chapter from my office in Austin, Texas last night! There were twenty-some in the room, plus an additional twenty or so online. This was a great turnout for a chapter meeting with a virtual component.

I found I needed the chat backchannel to get me through the blindness and silence on the phone – the audience was so polite and didn’t interrupt but I found myself constantly checking for feedback and realizing the only feedback I could get was from the WebEx chat window flashing orange and white every once in a while. And the discussion beforehand about Twitter (editing tweets and tweeting edits) was light and entertaining and certainly kept my nerves calmed by letting me snicker with my hand over the phone mic.

I’ve made my slides available on Slideshare and I hope you’ll comment there and ask any additional questions you may have. I was energized afterwards! I really appreciated the opportunity to talk about wikis and wiki-like documentation.

techpubs

Virtual presentation – Wiki-fy Your Doc Set for the NYC Metro STC chapter

Here’s the announcement for next week’s virtual presentation. To sign up, click through this link. There’s a limited number who can participate virtually so sign up soon!

Wiki-fy Your Doc Set: A Writer’s Role in Web 2.0

One of the hottest topics in technical communication today is the concept of collaborative document authoring, and wikis are emerging as the primary means of accomplishing this.

Anne Gentle, speaker at the April program, will teach you about wikis and writing, tell you of best practices from others who are implementing wikis, and show links to example wikis.

Anne will be discussing community building methods and experiences as a participant on wiki platforms, plus practical advice for motivating contributions.

In addition, where there may be reasons to not implement a wiki based on studying the potential community and time you’d spend in arbitration with community members, Anne will expose you to wiki benefits that you can borrow while still meeting your business goals.

This presentation offers opportunities to:

  • Learn from other examples of wikis used for end-user documentation.
  • Evaluate the advantages and known limitations of using a wiki.
  • Determine if simply adopting wiki-like technology would be sufficient for your environment.
  • Get some judo moves for defending your stance for or against a wiki.

This presentation is available virtually through LiveMeeting for people who cannot attend the meeting in person. Connection details will go out to everyone who RSVPs no later than 6:00 p.m. the day before the program.

techpubs tools

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.

Social networking and generalizations

I’ve seen a few too many email blasts and blog entries with a lead that dramatizes social media with these sweeping generalizations about age groups using social software. The average age of Twitter users is 32, so any line about 30-40 year olds is plain wrong. The average age of Facebook users skews upwards due to the pranking popularity of choosing “69” as one’s age.

Recent demographics from Facebook say that in the last 60 days (from end-of-March 2009), the number of people over 35 has nearly doubled. The fastest growing demographic on Facebook is still women over 55. Over 4 million more US women 35-44 and nearly 3 million more US men 35-44 used Facebook in March 2009 compared to September 2008. The majority of US Facebook users are now over 25.

Because the data doesn’t match these types of age scales, I cringe a little when I see age generalizations associated with social software.

There’s ethnographic data from danah boyd that describes that the actual difference between people using different social software sites is in fact class-based.

People are networking as always – and I’d argue, the usual is to relate more to people your same age in a similar life stage. But you miss out when you box people into age groups.

I blogged previously about the need for visibility into younger age groups to getting involved in associations like the Society for Technical Communication (STC). As a result, I had great pointers to 20-somethings who were doing neat things in the tech comm space. Tony Chung, your name came up! He’s a fellow blogger with me at the Duo Consulting blog. Another woman had been given her mother’s tech comm consulting business at a quite young age and was succeeding mightily.

Ann Wiley wrote a great email about how much age doesn’t matter when it comes to technology. And I agree, and I hope she doesn’t mind if I quote her here:

Those of us who came into the world in 1948 are blessed indeed. The horizon is very big, looking out from that year, and it gets bigger all the time. The war was over, our parents were indulgent, and technology came our way. The question is, what can we make of all that opportunity?

It doesn’t matter what age you are when you get into social technology, but your attitude does matter.

One last personal anecdote about the benefits of spanning generations in all your activity. One of my best running partners of all time is now in her seventies, and I ran at the same pace as she did when I was in my late 20s and she was in her mid-60s. She was and still is a faithful companion, a good listener, and a wonderful mentor and coach.

techpubs

Create your own innovation council

From Joann Hackos’ book, Information Development: Managing Your Documentation Projects, Portfolio, and People, Google Books shows this quote:

Excellent information design requires exposure to design innovations in the community.

As I finalize my work on a book about writing for the social web, including community, and integrating conversation, I can think of lots of ways to learn about innovations in the community thanks to all these technological connection methods we have available to us.

What other ideas do you have to learn about innovation?