Slashdot Mirror
Single Sourcing: Building Modular Documentation
Scott Abel writes "Kurt Ament has hit the nail on the head! His latest effort, Single Sourcing: Building Modular Documentation is a valuable reference for those of us who seek to save time, effort, and money by implementing a productive method of creating information once and reusing it often." It's not a big book -- just 246 pages. Read on for Abel's brief review.
Single Sourcing: Building Modular Documentation
author
Kurt Ament
pages
246
publisher
William Andrew Publishing
rating
10
reviewer
Scott Abel
ISBN
0815514913
summary
How to build modular documentation you can re-use in different formats for different audiences and purposes
Ament covers the issues -- step by step -- that many others only discuss. He lays out a simple roadmap, complete with real world examples that have worked -- or not worked -- for his clients.
In Chapter 1 (About Single Sourcing), he carefully defines "single sourcing" and explains related concepts (reusable content, modular writing, and assembled documents) in ways that are easy to understand and free of techno-jargon. And, he does us all a big favor by addressing the negatives associated with using technology to assemble documents by explaining that it actually takes more creativity to write content that can fit into multiple media, for multiple audiences, than it does to continually rewrite information over and over again each time it is needed.
Chapter 2 (Building Documents) and Chapter 3 (Structuring Content) are of particular value to those seeking to understand the shift in thinking required to master single sourcing. Writers, programmers and managers will all benefit from these chapters. Each chapter is packed full of tips and examples you can begin using today!
Chapter 4 (Configuring Language) explains how to "configure" your writing to support and increase usability while Chapter 5 (Leveraging Technology) touches on issues including conditional text, conventions, localization, translation, variables and more. As are the previous chapters, Chapter 5 is written in clear, concise language and is not a chapter business types should skip. In fact, it's just the opposite. Managers and decision makers need to understand the concepts explained in this chapter because many of the benefits a single source strategy can deliver are made possible by combining good planning with the right technology. And, while this chapter is certainly not about selecting software tools, the author helps his readers understand some of the issues they will need to understand as they begin thinking about their strategy and the types of functionality they'll need to support with the tools they select.
What I like most about "Single Sourcing" is that Ament went straight for the meat of the issues. He doesn't belabor points or confuse the reader by jumping back and forth from subject to subject (as so many poorly written IT-related books do). Instead, he supplies us with a book you can read in an afternoon and use the information contained within the next day at work.
But, be forewarned. You're going to want your sticky notes and your highlighting markers nearby. Chances are you'll be using them a lot!
In Chapter 1 (About Single Sourcing), he carefully defines "single sourcing" and explains related concepts (reusable content, modular writing, and assembled documents) in ways that are easy to understand and free of techno-jargon. And, he does us all a big favor by addressing the negatives associated with using technology to assemble documents by explaining that it actually takes more creativity to write content that can fit into multiple media, for multiple audiences, than it does to continually rewrite information over and over again each time it is needed.
Chapter 2 (Building Documents) and Chapter 3 (Structuring Content) are of particular value to those seeking to understand the shift in thinking required to master single sourcing. Writers, programmers and managers will all benefit from these chapters. Each chapter is packed full of tips and examples you can begin using today!
Chapter 4 (Configuring Language) explains how to "configure" your writing to support and increase usability while Chapter 5 (Leveraging Technology) touches on issues including conditional text, conventions, localization, translation, variables and more. As are the previous chapters, Chapter 5 is written in clear, concise language and is not a chapter business types should skip. In fact, it's just the opposite. Managers and decision makers need to understand the concepts explained in this chapter because many of the benefits a single source strategy can deliver are made possible by combining good planning with the right technology. And, while this chapter is certainly not about selecting software tools, the author helps his readers understand some of the issues they will need to understand as they begin thinking about their strategy and the types of functionality they'll need to support with the tools they select.
What I like most about "Single Sourcing" is that Ament went straight for the meat of the issues. He doesn't belabor points or confuse the reader by jumping back and forth from subject to subject (as so many poorly written IT-related books do). Instead, he supplies us with a book you can read in an afternoon and use the information contained within the next day at work.
But, be forewarned. You're going to want your sticky notes and your highlighting markers nearby. Chances are you'll be using them a lot!
Other resources:
- Kurt's site: http://www.infotektur.com
- Book site: http://www.infotektur.com/books/singlesourcing/ind ex.html
Scott Abel (abelsp@netdirect.net) is a content management strategist who assists his clients in planning and preparing for content management initiatives. Scott is a frequent presenter at industry and professional service seminars, an instructor at Indiana University Purdue University at Indianapolis Community Learning Network, and vice president of the Society for Technical Communication (STC), Hoosier Chapter. You can purchase Single Sourcing: Building Modular Documentation from bn.com, though new copies are currently out of stock. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.
Typo!
---- "Excuse me. Where's the children's gun section?"
fp
Where are all the FP Trolls?
Oh wait, I'm here.
YEs indeed, I know the score. Debian forever!!!1 BlowOS is doomed!
Actually I had the first post, but I chose not to use it to trol.
---- "Excuse me. Where's the children's gun section?"
CUCUCCUUCCUCUCUUCUCUCU hahaha nice typo, can you be more morons ? , no sure u cant
I'm just saying that maybe we need to focus on what's important. Like human rights for Iraqis
[ed. note: in the following text, former FreeBSD developer Mike Smith gives his reasons for abandoning FreeBSD]
When I stood for election to the FreeBSD core team nearly two years ago, many of you will recall that it was after a long series of debates during which I maintained that too much organisation, too many rules and too much formality would be a bad thing for the project.
Today, as I read the latest discussions on the future of the FreeBSD project, I see the same problem; a few new faces and many of the old going over the same tired arguments and suggesting variations on the same worthless schemes. Frankly I'm sick of it.
FreeBSD used to be fun. It used to be about doing things the right way. It used to be something that you could sink your teeth into when the mundane chores of programming for a living got you down. It was something cool and exciting; a way to spend your spare time on an endeavour you loved that was at the same time wholesome and worthwhile.
It's not anymore. It's about bylaws and committees and reports and milestones, telling others what to do and doing what you're told. It's about who can rant the longest or shout the loudest or mislead the most people into a bloc in order to legitimise doing what they think is best. Individuals notwithstanding, the project as a whole has lost track of where it's going, and has instead become obsessed with process and mechanics.
So I'm leaving core. I don't want to feel like I should be "doing something" about a project that has lost interest in having something done for it. I don't have the energy to fight what has clearly become a losing battle; I have a life to live and a job to keep, and I won't achieve any of the goals I personally consider worthwhile if I remain obligated to care for the project.
Discussion
I'm sure that I've offended some people already; I'm sure that by the time I'm done here, I'll have offended more. If you feel a need to play to the crowd in your replies rather than make a sincere effort to address the problems I'm discussing here, please do us the courtesy of playing your politics openly.
From a technical perspective, the project faces a set of challenges that significantly outstrips our ability to deliver. Some of the resources that we need to address these challenges are tied up in the fruitless metadiscussions that have raged since we made the mistake of electing officers. Others have left in disgust, or been driven out by the culture of abuse and distraction that has grown up since then. More may well remain available to recruitment, but while the project is busy infighting our chances for successful outreach are sorely diminished.
There's no simple solution to this. For the project to move forward, one or the other of the warring philosophies must win out; either the project returns to its laid-back roots and gets on with the work, or it transforms into a super-organised engineering project and executes a brilliant plan to deliver what, ultimately, we all know we want.
Whatever path is chosen, whatever balance is struck, the choosing and the striking are the important parts. The current indecision and endless conflict are incompatible with any sort of progress.
Trying to dissect the above is far beyond the scope of any parting shot, no matter how distended. All I can really ask of you all is to let go of the minutiae for a moment and take a look at the big picture. What is the ultimate goal here? How can we get there with as little overhead as possible? How would you like to be treated by your fellow travellers?
Shouts
To the Slashdot "BSD is dying" crowd - big deal. Death is part of the cycle; take a look at your soft, pallid bodies and consider that right this very moment, parts of you are dying. See? It's not so bad.
To the bulk of the FreeBSD committerbase and the developer community at large - keep your eyes on the real goals. It'