Slashdot Log In
Single Sourcing: Building Modular Documentation
Posted by
timothy
on Tue Apr 29, 2003 11:00 AM
from the docs-are-important dept.
from the docs-are-important dept.
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.
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!
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.
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.
This discussion has been archived.
No new comments can be posted.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
Full
Abbreviated
Hidden
Loading... please wait.
Use a wiki (Score:1, Funny)
Re:Use a wiki (Score:2)
Re:Use a wiki (Score:2)
Maybe, if you restrict access.
But I've seen way too many publicly modifiable Wiki pages collapse into a discussion about what Wiki is for/about.
Creativity? (Score:5, Interesting)
This would seem to be more of a reason to avoid modular doco. Creativity is not, shall we say, plentiful? at the typical workplace. And often, it isn't wanted when it is available.
Documentation professionals are creative (Score:3, Insightful)
From personal experience, I know that it's not that difficult to mark text as "internal use only" so the developers can quickly find the names and values of parameters and "end user only" s
Re:Documentation professionals are creative (Score:2, Interesting)
Re:Creativity? (Score:2)
Will they read the finer manual? (Score:5, Insightful)
I say take your money and buy a book on user interface design. The problem is not how well written the docucumentation is; it is the fact that we NEED the documentation.
Re:Will they read the finer manual? (Score:2)
Re:Will they read the finer manual? (Score:3, Insightful)
Re:Will they read the finer manual? (Score:3, Insightful)
It's all fine and good to make a great looking and intuitive UI whenever possible, but there's a lot of times when no matter how good a UI you make, the type of program (or device) it is will simply NEVER be intuitive enough to survive without some kind of explaination for what various widgets are for or what various errors/messages/etc mean.
The problem is many people hear "do
Yeah, who needs documentation? (Score:3, Insightful)
Too many engineers look at t
Re:Yeah, who needs documentation? (Score:2)
Re:Yeah, who needs documentation? (Score:2)
Absolutely right. But also beside the point. Even users who ignore documentation refer to it when they can't figure stuff out for themselves. Or at least some of them do. And when a user gets desperate enough to actually RTFM, they really need well-written docs.
A couple more points I just thought of. First, documentation does more than help users use. It also tells potential users what the product can do. When I consider buying software (o
Re:Yeah, who needs documentation? (Score:2)
Re:Yeah, who needs documentation? (Score:2)
Actually.... (Score:2)
You've reminded me of a conversation I had a very long time ago. I was going to a school that had no Computer Science or EE department. Programming was taught in various science departments (mostly M
A Better Command Line User Interface. Good Idea. (Score:2)
Because if only the hundreds of commands for which I maintain man pages had a decent user interface, those silly documents could finally be abandoned.
Then I could move on to more important tasks, like posting inane comments on Slashdot.
Comments like this one.
Online reading habits different? (Score:2, Insightful)
Very different from books, where the author is more able to exert without much fear of whiplash...
use XML (Score:5, Interesting)
Re:use XML (Score:4, Informative)
There are also various XSL and DSSSL stylesheets to convert the docbook xml into html, xsl-fo, pdf, latex etc.
Best thing with XML is, you can pack all of the documentation in one single place and create various documentations according to each audience (user, professional user, developer, etc) and language. There is no need to write duplicate informations, you only have to add certain attributes to the xml tags.
Parent
DocBook, sorta (Score:2)
Re:use XML (Score:2)
Ofcourse, at the end, it is *what* is being said that is more important and *how* -- than *in what format*.
The basic flaw these days among techies is that many don't write well. Changing the format is almost similar to chaging the typeface or the font.
S
Literate Programming (Score:2)
But embedding all your documentation in your source code is a very bad idea. That's the concept behind JavaDoc [sun.com], and I have the bruises to show how badly this works in practice. Writers and programmers tripping over each other. Programmers that don't know how to write markup or even prose. Writers that have to br
XML, yes, NBD, no (Score:3, Insightful)
Hey stalker! (Score:2)
Cheesy (Score:5, Funny)
Why not just submit a link, Scott? Sheesh.
Re:Cheesy (Score:2)
Maven does some neat stuff with documentation.... (Score:3, Informative)
....using Maven's [apache.org] xdocs, you can generate both HTML and PDF docs from the same XML source file.
We use this on GForge [gforge.org] and it works pretty well....
Tom
246 pages is not big? (Score:4, Interesting)
Here's a clue: Those big books are hugely padded by:
1. Large margins so there can be a little note every few pages.
2. Repeated program listings, also with huge margins.
3. A hundred or more pages of fluffy introductory chapters ("What is a programming language?").
4. Massive redundancy.
Personally I'm waiting for the return of slim, readable books.
Re:246 pages is not big? (Score:3, Insightful)
I'm sick and tired of having concentrate in order to locate "the point" within masses of text. K & Ritchies ANSI C book sets a fine standard for concise technical books. A fine example for Java is "Java Precisely", http://www.dina.dk/~sestoft/javaprecisely/
Re:246 pages is not big? (Score:2)
I absolutely agree. Note, however, that my copy of K&R, 2nd edition, is a slim 272 pages -- longer than the book being discussed! 246 pages is a slim book indeed.
Re:246 pages is not big? (Score:2)
K & Ritchies ANSI C book sets a fine standard for concise technical books.
Beyond setting a fine example, K&R is a positive indictment of thick books:
"C is not a big language, and it is not well served by a big book"
Beautiful, so beautiful. sed "s/C/[many languages]/".
Re:246 pages is not big? (Score:2)
Re:246 pages is not big? (Score:2)
5. Voluminous reprints of public domain and easily accessible information.
Linux Unleashed was the first (and last) "big" tech book I've bought. That book turned out to be a simple reprint of the man pages that led me to look for a book in the first place. I regretted buying that book so much that it really helped me set my priorities for later purchases.
246 pages, only? (Score:3, Funny)
Paper is near passé.
And, new topics like this is often extensively referenced at popular sites like Slashdot [slashdot.org]; do yourself a favor and check it out!
Kudos (Score:3, Insightful)
I remember providing input to a tech writer, then red-lining the first draft to the point that rewriting the entire document seemed necessary. While I would rather write PHP or scripts, there is no one who better understands code than its author.
Today's on line documentation provides a variety of methods for an engineer to provide documentation. Such examples are:
How to's and Mini How To's
FAQ
Web page with screen shots
Forums and Blogs
That being said, I am reminded of a conversation with Clyde, a retired avid sailor, who talked about stories in "SAIL" magazine. "First person stories written by sailors usually suck!" he said. "Give me an article written by a professional writer. They're easier to read."
It's easier to write documentation than to try to tell someone what to write. ....Now if only I can break away from coding long enough to read this document on creating documentation.
You stick to coding and let me handle the docs... (Score:3, Insightful)
Blockquoth the poster:
You're right -- but it takes a LOT more than that to produce clean, usable documentation. And yes, I speak from experience; I've been a technical communicator for more than eight years, and I've spent the last two years just cleaning u
turning point? (Score:5, Interesting)
The core concept of arbitrary display and formatting of structured text, which appears to underly this new work, remains alien to most of the people making business decisions and authoring documents. When you combine a vacuum style lack of good tools to author documentation in the target technology with a flood of readily available "old paradigm" authoring tools for making stuff look pretty (word processors and desktop publishing stuff) you get the explosion in documents that was seen in the 90's. You also get the tremendous resource drain as these docs are updated and reformatted for subsequent generations of word processor formats that continue to mix content and presentation. We also see a direct parallel problem with the amazing fanatical market success of programming environments where logic and presentation are mixed (MS.asp, PHP, etc.) over object oriented tools. Far, far more dynamic web sites are built "the old fashioned way" despite the availability of decent, even "better" authoring tools that exist in the object oriented world.
Unfortunately most organizations that produce and use documentation do so as an aside at best, or an afterthought at worst. Organizations typically don't value documentation highly enough to create job descriptions for skilled technical writers. Corporations with IT staffs of hundreds of people - managers, systems administrators, help desk workers, developers -- often don't have a single Technical Writer.
Take the help desk as a primary example. Just about every big company produces volumes of documentation for use by the help desk workers. Sadly, much of that documentation is created after the fact, by desperately struggling front line help desk workers themselves, who randomly try to assemble facts and myth about problem resolution. The folk creating the systems are generally not given sufficient time to develop and maintain documentation, often barely enough resources to develop the system in the first place, before moving to the next task. It's rare for companies even to realize the blatant "in your face" opportunities to save money by investing in better documentation.
If we can't get developers to understand this basic concept, how can we get front line help-desk workers who are writing documentation for themselves out of desperation and under the clock of "you still gotta answer twenty calls an hour and resolve 19 of the problems before hanging up"? Even better, how do we get a bureaucratic organization to invest in skilled technical writers?
It seems to me that to get to this point we will need to create authoring tools that are so powerful and easy to use that the authors of documentation don't need to think about the separation of content and formatting -- it "just happens" in the background. Anybody who writes such a tool gets to spend the rest of their life retired on a beach, earning twenty percent and drinking rum from hollowed out pineapple shells with little paper umbrellas in them.
Re:turning point? (Score:3, Interesting)
I'm mired deep in tha
Full Disclosure Please (Score:2, Interesting)
How do I know the author isn't benefiting from writing his glowing review here in some way? I'm not accusing the reviewer of any misbehavior here, but when the only negative of a book is that "But, be forewarned. You're going to want your sticky notes and your highlighting markers nearby" I have to question the bias of the reviewer.
Sample review checklist
1. Have you contributed to this book or been cited
Excuses.... (Score:3, Funny)
Single sourceing: Tech Writing's Newest Boondoggle (Score:3, Interesting)
Writing good documentation is hard work. It seems to me that the only people who benefit from "single sourcing" are the people who are writing these books and giving overpriced lectures to rooms full of unemployed tech writers.
Ultimately it won't improve the clarity or usefulness of your documentation. It won't provide you with the ability to understand the subject or the audience any better.
Don't get me wrong, if there were a magic-bullet that single source claims to be, I'd be all for it. It would be nice not to have to worry about document formatting. But personally, I think it's simply another way for organizations like STC (The Society for Technical Communication) to filch money from their members.
Re:Single sourceing: Tech Writing's Newest Boondog (Score:2)
My beef is that there's minority groups in the overly influenced world of tech writing that have convinced many others that "single sourcing" is a recipe that you can pay to learn at a three-day lecture, then go out and write great documentation.
In the majority of cases, what single sourcing turns out to be is a great waste of time and effort. In my expe
Re:Use Eiffel (Score:4, Funny)
(Calm down, it's meant in gest.
Parent
Re:Use Eiffel (Score:2)
Re:Use Eiffel (Score:2)
Re:Use Eiffel (Score:4, Informative)
Design by contract won't make your code any more self-documenting than design by committee.
If you want self-documenting code, write something ridicoulusly simple. If you are doing something hard, you need explanation beside the code (unless you assume that everyone reading the code will be a domain expert, but in that case I wouldn't call it self-documenting).
Eiffel isn't even designed to be self-documenting. It is designed to facilitate run-time (and in some very few cases: static) checking of program invariants, preconditions and postconditions. This will help for correctness, but not much for documentation. In many cases, the code will be easier to understand without them. (Not that I would recommend it, I do like DbC, but only as means to correctness, not as documentation).
Sure, writing down assertions will in some cases help you in how to use an interface, or help you with other underlying assumptions in the code, making it easier to change something without breaking it. But it will never tell you anything about what the code is supposed to do, why it's supposed to do that, and why this way has been chosen to do it.
Now, go re-read your Eiffel book, and come back evangelizing it when you understand it's purpose!
Parent
Re:Wonderful review, only one question (Score:3, Informative)
For more information:
http://www.stcsig.org/ss/index.htm
RUP in hacker terms... (Score:2)