Subscribe to RSS
Posts Tagged ‘content’
Progress on the Conversation and Community book
The final details for my book, Conversation and Community: The Social Web for Documentation, are coming together. Lots of news to report, so here goes.
I’m so excited to announce that Eliot Kimber has agreed to use my book for the DITA for Publishers project, taking the content from Adobe InDesign to DITA.
Tom Johnson also posted a fun interview he recorded during the STC Summit. I told Tom, I can hear myself grinning. This book is just fun to talk about.
I’m often asked, how long have you been working on it? I answer that I’ve been working on it for over a year now. It combines lots of stories from my corporate blogging days at BMC Software with my foray into the open source community with the One Laptop per Child project, SugarLabs (the education project that runs the open source software on the OLPC laptop), and most importantly, FLOSS Manuals, providing free software for free documentation. My thirty-hour work week at ASI has afforded me the time to write out my journey and my observations along the way.
What a journey it has been and I’m so pleased with how the book is turning out. This week I am furiously indexing (is there any other way to index besides furiously?) and often messing with recto and verso pages, something I haven’t done in InDesign before and boy does it show. My PageMaker days as a graduate assistant at Miami University’s Center for Chemical Education are coming in handy, no doubt about it.
I think we’ve finalized the cover design, which for me is a very exciting part of real bookmaking! I’ll see if I can share it on my blog soon.
Four fine people have agreed to do technical reviews and I know some of them are at least 100 pages in. I hope they have insights – but not too many that may cause me to think too hard. Just kidding, Alan, Will, Sarah, and Scott! 
Keep reading and keep your notes at the ready because I’m ready to make all the changes needed to keep this project rolling. This book’s time has come.
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!
InfoSlicer is released to the world
Let the remixing begin. I just got word today that the Infoslicer project has been checked into the Sugar code repository at http://git.sugarlabs.org/projects/infoslicer, and released under the GPLv2 license. Can I get a whoohoo? Oh yeah!
Infoslicer is a Sugar Activity that enables students and instructors around the world to assemble Wikipedia articles into new information packages. Under the covers one of the technologies that makes this possible is the Darwin Information Typing Architecture (DITA). I first wrote about the InfoSlicer last fall, in Wikislicing project gets real – introducing InfoSlicer as a Sugar Activity with a picture of students using scissors to re-assemble Wikipedia articles.
If you want to download the Activity to your XO or another computer with Sugar installed (here’s how) to try it out yourself, go to http://sugarlabs.org/go/Activities/InfoSlicer and install the Activity (here’s how).
I have downloaded it to my XO in anticipation of showing it off at the next XO Austin Users Group meeting and the install was straightforward. I’ll get it on a USB stick to share at the meeting (2/16 at Central Market on N. Lamar in Austin at 6:30). Here’s a screenshot – and be sure to check out the YouTube video!
Laura Cowen notes that the xo package that you download doesn’t contain any sample articles from Wikipedia (which ideally it would to help you get up and running more quickly using the tutorial). You can use InfoSlicer without these sample articles (you download Wikipedia articles from within InfoSlicer anyway). If anyone is able to re-compile the xo package with sample articles in it, Laura can provide instructions on where to put the sample articles in the package so that InfoSlicer automatically picks them up when it starts. Who wants to create the wikislice seen ’round the world?
How does search affect delivery and presentation methods?
Search technology and its application by our users is an ever-growing aspect of technical documentation today. How many times have you seen “I found the following Microsoft Knowledge Base article using a Google search.” (or have you been guilty of doing the same yourself?) I say “guilty” because it’s funny that Microsoft has built the best content site in their Knowledge Base and yet a competitor’s search engine brought the user to the site.
Sure, any knowledge base absolutely must have a search engine and search box available to visitors to the site. A manual of some sort was once a requirement for a consumer product, but I’m not sure if a book-like manual is a requirement any more. Will the custom crafted search engine go the same way?
In the case of someone finding the content using another search engine, it means that for that particular visitor, all the resources and time and money spent on providing a search engine specific to that knowledge base was wasted. There was zero return on investment for the search engine but all return on investment on the content itself.
STC2008 – From Nightclub DJ to Content Management Consultant
Subtitle: Developing a Business Career The Content Wrangler Way
From the ever entertaining Scott Abel, this was an invigorating session that still kicks you in the butt to get out of your whiney mode and into a winner mode. Sounds cheesy to repeat, but it worked. Here are my notes from the session. I’d love to hear your thoughts and critique on my “live blogging” style – too much information, not enough information, not the right information? Let me know.
Routes to tech comm – English major or developers accidentally become tech writers
scottabel.com – crafted a career – but Scott didn’t grab that URL (he’s obviously not That Scott Abel.:)
He earned 146 credit in four different programs, and didn’t earn a degree
he could get a college degree, but decided not to pay the “fees.”
Still takes classes like knowledge enabled information management – Indiana University 8-5 every day for three days, presentation to 200 people as a capstone, and you fail if you’re late, or don’t play by their rules. But it’s three credit hours.
John Herron school of art in Indianapolis – foundational school – you should have drawing or sculpting skills, though.
Business School, next stop – he lasted one semester, it wasn’t about the answers, it was about how you get the answers – answers are on the back of the syllabus
Next stop, photography – first working with digital photography, won some photography contests by accident.
Journalism school – at Indiana University – and he worked there too. He went to and helped with computer assisted journalism conference. Use computer technology to cull through all the data.
He started in entertainment journalism, friend of Margaret Cho, has interviewed Elton John, other celebs.
Started a local alternative magazine… fun exciting and profitable. Assignment in journalism school – business plan for a magazine… just did the magazine, didn’t do a plan. 72-page monthly publication, two guys with two much time on their hands – sold highscale ads and actually made revenue.
He waited tables to get through school, learning that he could make 200-300 bucks a night, he met influential people. PanAm games, miniature Olypics hosted in Indy, got more experience.
He had the attention span of a worm – didn’t lead to very many opportunities.
Became a bartender – clock in at midnight, clocked out at 3-4 am. But felt he lost time during those “young” years even though he had flexibility and enough money.
Age 14: my first gig as a DJ. Learned how to mix, taught him about content reuse and personalization… wrong song – every one hides like roaches. or perhaps on purpose, when music sucks, beer and drink sales go up.
Wrong song, wrong version of the song. He had a remix of a chitty chitty bang bang that got played on Chicago radio.
Remixes were user-generated, 45s were all they had to work with, they’d buy 2 copies of the single, because they needed songs longer than 3 minutes. So… two turntables and a mixer – had to understand tempo, tone, feel of a song, but tempo control was the key. The Technicas 1200 Turntables are still instrument of choice for many dejays.
Reuse is in the remix… that’s how tracks were laid down… vocals reused identically but combined with different styles of music.
Madonna explained how her voice could be changed, the tools allowed her voice to stretch like a proportional sqaure stretches proportionally when you hold down shift key…
DJ mixing and increasing complexity similar to content choreography that we do with content – the technology is increasingly.
1999 – employment counselor said, you’d be an excellent technical communicator with your skill set.
Put together a portfolio
First job, documenting mortgage loan automation software, $45,000, he could buy groceries, kick out his roomates. Bedazzled by corporate America… benefits, paycheck, vacation.
Had folders called “Betsy’s documents” – totally disorganized, inefficient, wasteful, later they were sued out of business. Their automated software was
Started reading Ann Rockley, Bob Glushko, JoAnn Hackos, all of whom had really good best practices towards fixing the mess of content he was seeing at work.
Ann Rockley sent Scott a draft of her book, Unified Content Strategy, and he became technical editor on the book.
He needed a way to get organized, get away from notes on paper in his backpack, started a blog to be a storage container for his knowledge.
(Side note – I have to enter my “cringe” essays from grad school)
Once he got attention for his blog, he got more people talking to him, asking questions, help solving questions.
Started speaking at events, but then had to define his value proposition. Rebranded himself as a Content Management Strategist.
Tools that can tell management that content is valuable and that the product can’t ship without it. Value proposition can’t circle around their job – content needs to be valued.
Syndicate Conference 2006, encouraged to think bigger. He started commoditizing the site. Conference are a natural extension of what he was writing about, his readers wanted to learn more about what he was writing about.
Presenters seek attention – same folks who speak at conferences write articles and participate in groups.
Need for a community – 1900 members of the Content Wrangler community… there needed to be a way for people to connect to one another without Scott’s help.
Being an individual consultant is not scaleable – and this is good news for you. You can create your own value proposition.
The discipline of Document Engineering – Bob Glushko, no future in commodity writing – the future is in solving content challenges. Structured content, XML, move content around, but not just documents – documents married with data from databases. Opens up a brand new world.
Road to success – don’t allow others to define you, no one right way to become a content management expert.
Questions?
He’ll post to slideshare.net (youtube for ppt)
scribd.com (youtube for pdf) ipaper service
http://thecontentwrangler.ning.com Community site
Harmonizer product – will eventually let you analyze content using web page
How much coding does Scott know?
If you don’t know how to model content, you shouldn’t be coding. You have to be able to analyze content before you model it, even.
What’s next for Scott – providing service designs, such as RSS feeds. Problem solving providing services that give them answers before they ask them. Such as mortgage being due, or governments issuing fishing licenses.
Another question – any certificate programs you’d recommend? None, says Scott. Writing for reuse isn’t part of these certification programs, what about DITA, often focused on tools, not skill differentiators.
Putting content into context in a wiki – especially in a large environment
An interesting read on the front page of wordpress.com of all places. I enjoy random clicking, and this one came up with a great commentary on the difficulty of using a wiki to get how to information.
From Learning about Second Life from Google:
Over at SL, the main source of information is on the WIKI, which in my opinion has some great information but because Linden primarily lets the users run the show isn’t as helpful as some sort of information clearing house. Trying to sort out how to sculpt, for example, is an exercise in total frustration. There are some wonderful tutorials, but SL does nothing to properly aggregate and put these tutorials into context.
I wonder what Second Life could do to properly aggregate those tutorials to meet this user’s needs? I suppose long-time wiki writers would answer: use categories and encourage tagging, while looking out for orphans. Any other ideas?
I got a great question from Tom Johnson of I’d Rather Be Writing:
I’m just wondering if you have any thoughts on the WordPress Codex, http://codex.wordpress.org/Main_Page. Yesterday I was looking at this Codex wondering what to make of it all. I think I want to be a contributor, but there are so many topics. It’s chaotic. The organization is like a maize. I don’t know if I should go in there with a wrecking ball and rennovate, or not. Probably 25% of it is outdated. What happens to those outdated pages? Will I offend people if I just delete things that are outdated?
Can you recommend a book or strategy for making sense of massive wikis? Where should I start? I spent a good hour editing a page of it last night that I considered critical. It’s then that I realized this is a huge project and I have no sense of direction. Any insight you can give me would be much appreciated.
With the OLPC wiki, David Farning on the Library list went through the wiki and said he found these categories. It’s quite an accurate content analysis from what I’ve seen, so I was impressed. At the same time, it also helped explain my initial wonderment at how to wrap my arms around the entire wiki – and in fact, it is barely possible to do.
Content
1 Philosophy
2 Contributing
3 Creating
4 Curatoring
5 Projects
Deliverable
In progress
Ideas
6 Management
Once David came up with these categories, he then asked SJ Klein, director of community content and long-time Wikipedian, if he thought the wiki needed structure.
SJ said that the wiki is purposefully without hierarchy – flat, especially for projects, to not force a parent or sibling sense for projects. He also said, however, if you have a specific tree hierarchy in mind, feel free to develop the idea in some temporary space.
So, when working on a large wiki if you have good organization ideas, set them up, and then ask for community feedback. Seems like an appropriate approach to a large wiki.
Other ideas for starting out in a large wiki environment:
While it might seem like it’s a question similar to “how do I get started on a huge writing project?” in my experience, wiki editing has some subtleties due to the collaboration and community vibe already present behind the pages. You have to work harder to figure out that vibe, and then determine your course.
For new people, there’s the whole question of getting a feel for the community so you can start to answer “who am I going to potentially irritate by editing this” and “as a newbie do I have the confidence I’m right?”
So, knowing your role within the wiki community is a first step. You might take a while to get to know who’s there, what their roles are as well, and where you might best fit in. Introduce yourself with your profile page, following the WikiPattern, MySpace – see http://www.wikipatterns.com/display/wikipatterns/MySpace.
Just like a newbie on a writing team, find out if there’s some scut work that you can do to get your feet wet, if needed, to gain the community’s trust.
Deletions are going to bring much more wrath in a wiki situation, I would guess, so they seem risky to do to start out. If you do think something needs deletion, message or email the original author or the big contributors and ask if it’s okay to mark it for deletion. Then, mark it, and hope that someone else (a wiki admin) determines if it should be deleted.
Start small, like tagging, or applying templates. That’ll help you get a feel for the bigger picture.
Let us know your ideas for wrapping your head around a large wiki, we’d love to hear them.
Wiki as online help source
A response to the question, Wiki-to-Help? on the Help Authoring Tool Yahoo Group.
One of our test engineers (and the lead developer of our company wiki) just approached me with the idea of using our company’s internal wiki as the central repository for all company material and using it to generate online help.
I’m following the discussion with interest. I, too, had a similar question asked of me from a developer when we were working in an Agile development environment at BMC Software. In that case, which was at least three years ago, the matchup between the wiki HTML output and the HTML output I needed for our particular help system just wasn’t a good fit. But today, there are better pairings, input to output. I think it’s feasible to go from a wiki to an online help system. It really depends on what output you need, and what you’re willing to do to ensure that the wiki source is worthy of publishing (tested, vetted, trusted, and so on).
I’ve been working on wikis as source for manuals, where the output is a PDF file. In general, yes, wikis are a little clumsy to work in for authoring. For example, some wikitext doesn’t understand that you want a numbered step list with images in between each step and that you want the numbering to continue after each image. So if you’re accustomed to a nice HTML authoring interface, a wiki authoring interface will “feel” like a step about 10 years back in time.
On the more interesting issue, the cultural issue (or the career issue, depending on how you think about it), I think the basis of most arguments against using wikis as source is the fear of loss of authoring control. See wikipatterns.com for the many anti-people patterns that wikis tend to foster if you don’t take steps to avoid them. I especially liked one of the responder’s comments to the list that he didn’t want to become an editor for a wiki. I think he’s right – that “magazine editor” is one of the roles you could take as a wiki-based author. You could also consider your role to be “community director” if you think you can motivate others to contribute to your wiki that will eventually be the help system. There are different roles that will evolve, and it’s up to you to figure out what role might work well in your environment (or if it would work at all). I wrote up a blog post last week about determining where your role as technical writer is most valued in the company, and building from that role.
I believe the cultural or social difficulties are the more difficult hurdle – you have to ensure that the community surrounding a wiki (those that can and will edit) is a group that is willing to work together and collaborate towards the common goal of publishing a customer-facing help system from the wiki. In a SXSW Interactive session titled “Edit Me! How Gamers are Adopting the Wiki Way” one panelist said that a core group of five editors on a wiki may be the best practice for the size of the group. This type of small number is represented and described in the 90-9-1 theory on wikipatterns.
A solution that might help you wrap your arms around the wiki as source is to set aside only one area or category of the wiki as the articles from which the online help gets generated. Again, without knowing the wiki engine you’re working with and the types of output you’d require, it’s difficult to know if a “wikislice” solution could help in your situation.
Anyway, I could go on and on (and I believe I just did go on and on) about using wikis as source for end-user documentation. I’m pleased that Sarah O’Keefe has just published a white paper titled “Friend or Foe? Web 2.0 in Technical Communication” that should be helpful as we begin to define our roles in each company and how we integrate user-generated content with our own on our product’s web sites.
I hope this information can help you build an argument for or against the use of wikis as source for online help. Please let me know the eventual outcome, and I’d love to hear your thoughts on my response.
DITA and wiki hybrids – they’re here
Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.
This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.
Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.
Lisa has made her presentation available online. My notes are below the slideshow.
[slideshare id=301959&doc=lombardi-wikis-model-1205252771520550-4&w=425]
DITA source to wiki output case study
Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.
What wiki toolset – open source or entprise wiki engine?
On the question of choosing an open source or enterprise wiki engine, Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help? They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note – I’m opining on whether you get updates to open source wiki engines through community influence. I’m certain you can pay for support and enhancements to open source efforts with dollars.)
Run a pilot wiki project
She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.
Meet customer needs – or decipher what they want and need
Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine – RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.
Intelligent wiki definition and separate audiences for each wiki
They have two wikis – one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.
Getting DITA to talk wiki
There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be – but in my estimation, they’re not completely awful either.
While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.”
Creating a wiki table of contents from a DITA map
She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.
DITA conref element becoming a transcluded wiki article
Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.)
Burst the enthusiasm bubble, there are limitations and considerations
One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful – “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way – and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”
If you’re interested in a copy of the case study, you can purchase it for $10 here:
What does DITA have to do with wiki?
We tackled this question and then some at the January Central Texas DITA User Group meeting. I’m a little tardy in writing up my notes and thoughts about the presentation but it went really well and I appreciate all the attendee’s participation as well. We had a high school teacher in the audience and I applaud him for wanting to learn more about DITA to pass that knowledge on to high school students.
I brought along my XO laptop since I was talking about my work with wiki.laptop.org and Floss Manuals and found some more Austin-based XO fans, so that was a great side benefit to me as well.
One of Ben’s answers to the question “What does DITA have to do with wiki?” is “Maybe nothing.” Love it!
Ben introduced another the triangle of choices – you have likely heard of “cheap/good/fast, pick two.” How about “knowledge/reuse/structure, pick one.”
I have to do some thinking about that one and his perception of the limitations and tradeoffs offered by those choices or priorities. Reuse and structure are particularly difficult to pair but also give you the most payoff. Structure and knowledge are another likely pair, but it could be difficult to find subject matter experts who are also able to organize their writing in a very structured manner, and finding writers who know DITA really well and also have specific content knowledge may also be difficult to obtain. His workaround for the difficulty you’d face while trying to come up with a structured wiki is a sluice box – where raw, unstructured data is the top input, some sort of raw wiki is the next filter, and the final tightest filter of all is a topic-oriented wiki.
Original photo of a sluice box by t-dawg.
My take on the question is that there are three potential hybrid DITA wiki combinations, and Chris Almond at this presentation introduced the fourth that I have seen, using DITA as an intermediate storage device, interestingly.
The three DITA-wiki combination concepts I’ve seen are:
- Wikislices – using a DITA map to keep up with wiki “topic” (article) changes. Michael Priestly is working on this for the One Laptop Per Child Project (OLPC.)
- DITA Storm – web-enabled DITA editor, but not very wiki-like. However, with just the addition of a History/Revision and Discussion tab, and an RSS feed, you could get some nice wiki features going with that product. Don Day had an interesting observation that sometimes when you add in too many wiki features on a web page you can hardly tell what’s content and where to edit it. I’d agree with that assessment.
- DITA to wikitext XSLT transform- but no round trip, have writers determine what content goes back to DITA source. Lisa Dyer will describe this content flow in the February session.
The slides are available on slideshare.net. Here are the slides that Ben Allums, Ragan Haggard, and I used.
[slideshare id=239223&doc=what-does-dita-have-to-do-with-wiki-1201150920945468-2&w=425]
Here are Chris Almond’s slides and his blog entry about the presentation. I described Chris’s project to Stewart Mader of wikipatterns.com and he blogged about our presentation as well at his blog ikiw.org.
[slideshare id=246329&doc=redbooks-wiki-central-texas-dita-ug-presentation-1201665419585231-4&w=425]
Anne Gentle is the author of 
