Catch up on stories from the past week (and beyond) at the Slashdot story archive

 


Forgot your password?
Close
typodupeerror
×
Programming Books Media Book Reviews IT Technology

Single Sourcing: Building Modular Documentation 130

Posted by timothy 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.
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!

Other resources:

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.

Single Sourcing: Building Modular Documentation More

Single Sourcing: Building Modular Documentation

Comments Filter:

  • Use a wiki (Score:1, Funny)

    by Anonymous Coward
    That way you have documentation, not docucucucucucucucucucucucuumentation.
    • Wiki is indeed a very nice tool to create collaborative documentation. It's also very useful to organise your own notes, links, or what you have gathered on the Web. I use TWiki http://twiki.org since two years, it's one of the best wikis in my opinion, I put in it everything I need, my todo lists, my install notes, interesting articles, a very nice way to create you own knowledge base.
      • Wiki is indeed a very nice tool to create collaborative documentation.

        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.

    • Wikis are a lousy way to maintain technical documentation!

      In order for technical documentation to be useful, it must be clear, complete, correct, and up-to-date. Wikis do nothing to insure these qualities. In fact, the best model for insuring them is a central maintainer (a person or a team). A central maintainer can also insure another quality missing from Wikis: consistency!

  • Use Eiffel (Score:1, Troll)

    by afidel ( 530433 )
    Because of design by contract the code is pretty much self documenting.

    • Re:Use Eiffel (Score:4, Funny)

      by BlueGecko ( 109058 ) <benjamin.pollack@ g m a i l . c om> on Tuesday April 29, 2003 @12:26PM (#5835040) Homepage
      Because of design by contract the code is pretty much self documenting.
      Well, so's COBOL, but that's hardly a strong argument to use it.

      (Calm down, it's meant in gest. :)
    • Because of design by contract the code is pretty much self documenting.
      I got the impression from the review that this book addresses the problem of assembling different forms of end-user documentation from a single source. While I agree that DBC is an excellent tool for documenting the code's internal interfaces and implementation, that's not going to be very useful to the non-programmers in your audience.

    • Re:Use Eiffel (Score:4, Informative)

      by joto ( 134244 ) on Tuesday April 29, 2003 @03:34PM (#5837009)
      Use Eiffel

      Because of design by contract the code is pretty much self documenting.

      Yeah, right!

      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!

  • Creativity? (Score:5, Interesting)

    by chmod000 ( 123913 ) on Tuesday April 29, 2003 @12:11PM (#5834882)
    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.


    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.

    • I think that a lot of this information is aimed at documentation professionals (technical writers, content strategists, knowledge management system workers, there are a lot of titles) who are very creative and love to work with these systems, rather than analyst/developers who view documentation as an evil waste of time.

      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
      • I somewhat agree ... i've worked on a few projects where the management had a wild idea that we could create content that could be used for web pages, user manuals, maintenance manuals, etc. with no further human intervention ... they had not thought about the limitations of the presentation medium. Realistically, the best you can do is create "chunks" that are easy to recycle because they are not contaminated with irrelevant information, have a consistent style, and do not depend on outside infomation.
      • I am a developer, but not one of those that considers documentation evil. Not at all--it's just like another program in my experience. I'm all in favor of building "reusable" doco, insofar as this is possible. The trouble with it is, the machines have no choice but to run the proggies you write for them. But, as has been noted by many, "People are a problem". Remember "RTFM"?

        Given the sort of doco that usually crops up in what I laughingly think of as "real life", the prospect of having the most odio

    • Actually, it's a reason to not go plunging willy-nilly into a modular doc project.

      Yes, it takes a bunch of creativity and up-front effort to pull it off. But the payoff comes when it's time to put out a new version of a large doc set, or if you have to publish in multiple formats. We have a system we developed in-house (using Framemaker as the foundation) that we can use to pump out printed manuals, PDFs, raw HTML, compiled HTML (.CHM), and Windows Help, all from one set of source files. We could do other
    • 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.
      Gawd, I wish I could say you were wrong. But you're not. Still, you have to ask why creativity is in such short supply. If you go out of your way to make a job (like document authoring and maintenance) pure drudge work, only dull stupid people will want to do it.

  • make ambigeous (Score:1, Interesting)

    by Anonymous Coward
    ./configure --enable-mod=ambigeous
    make
    make test
    make install

  • Will they read the finer manual? (Score:5, Insightful)

    by SourceHammer ( 638338 ) on Tuesday April 29, 2003 @12:12PM (#5834893) Homepage
    It seems that no matter how much I spend creating documentation, the users of the system don't use it, don't know how to access it, won't use it.

    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.
    • I don't agree. Manuals have been around as long as machines/software. You can't expect someone to begin working with a complex program and discover all the features by him/herself. So while i whish it were true, not everything in life is plug and play. furthermore, manuals can also teach you clever ways to use the program and get things done.
      • I know more about computer systems than 99.99999% of people yet I think I have consulted manuals proper about 5 times, mostly man pages. The rest is gleaned from web pages or just poking at the software.
    • Documentation isn't for the silly users, its for the poor sap that has to maintain your code =)
    • Although what you say may be applicable to user interfaces, that is just a fraction of the documentation to consider. I can think of any number of proposal documents where we take a modular approach to sections: it's called boilerplate. When you have several proposals in the same line of work there's a lot of cut and paste from submission to another. On individual projects there are system design specs, operations & maintenance manuals and more. Your assertion does not apply in these instances.
    • I believe the quote goes... "Documentation is like sex. When it's good, it's really good. When it's not, it's better than nothing."

      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
    • I take it you write your own user docs. Have you considered the possibility that you're not very good at it? Do you know how explain complicated features in a simple manor? Do you have the patience to discuss nit-picky details that you know intuitively but about which your users are totally clueless? Do you know how to organize an immense body of facts so that the reader doesn't go crazy trying to find one small unimportant fact -- unimportant to you, but essential to the user?

      Too many engineers look at t

      • I do not write my own user docs. I assert that even well written documentation mostly gathers dust. Maybe the problem is that too many bad documents got out there and because of the user's expectations of more of the same, users have given up looking at them. More likely it is the same syndrome that keeps people from reading the instructions when assembling a tricycle on Christmas Eve.

        • I assert that even well written documentation mostly gathers dust.

          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

    • It seems that no matter how much I spend creating documentation, the users of the system don't use it...

      Put more porn in it
    • 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.

      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)

    by Anonymous Coward
    One thing I've noticed over the time i've spent surfing is that most online content has to get straight to the point with as little fuss as possible. If an article can't capture the interest of the reader within the title, or follow up within the first few sentences, people often quit reading and move on. I actually wonder how many people RTFA in slashdot.

    Very different from books, where the author is more able to exert without much fear of whiplash...

  • use XML (Score:5, Interesting)

    by stonebeat.org ( 562495 ) on Tuesday April 29, 2003 @12:26PM (#5835044) Homepage
    use XML. provides re-use of content. no big deal. and now there are collaborative XML editors, which allows authors to work on various sections of the same document.

    • Re:use XML (Score:1, Insightful)

      by Anonymous Coward
      >provides re-use of content

      oh yeah? can you explain how?
      • Seriously, is there anything that XML doesn't do? You can use XML to structure your documentation such that creating multiple presentations of it is automated. However, creating modular documentation that can be pieced together to create totally seperate documents is a whole other problem, and much more difficult.

    • Re:use XML (Score:4, Informative)

      by Ozan ( 176854 ) on Tuesday April 29, 2003 @12:49PM (#5835297) Homepage
      And there is already a nice DTD for documentation called DocBook [docbook.org].

      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.
      • DocBook is cool. I'm writing a book using it. But it's not the format for all technical content. If you're writing your basic mass-market computer book, or the web equivalent, DocBook probably has everything you need. (Though the markup for the official DocBook reference [oasis-open.org] is forced to use generic tables to list element parameters -- there's no specialized element!) But I'd hate to use DocBook for a big API document base, especially one where single-sourcing is an issue. IBM's DITA [ibm.com] framework is immature, but
    • Isn't it a little too cumbersome to "write" via XML? "Literate programming", where the documentation and the code are tied in, may not be a bad idea.

      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 has its place. Encouraging programmers to describe and implement in one pass is definitely a good thing. It makes for products that are better thought out and easy to maintain.

        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

    • "use XML. provides re-use of content. no big deal. and now there are collaborative XML editors, which allows authors to work on various sections of the same document."

      Have you ever produced content that was successfully "repurposed" without re-editing, just by using information embedded in the text at the time of creation? In other words, parsable something (SGML. XML, or whatever) that produced complete and coherent presentations with no human intervention after the initial content was produced?

      That h

    • XML, yes, NBD, no (Score:3, Insightful)

      by fm6 ( 162816 )
      Yeah, XML is da bomb. I wouldn't use any other format to maintain a non-trival document base. Especially one where single-sourcing is important. But "no big deal"? Guess again.
      • There are no affordable off-the-shelf content managment for most technical documentation apps. Yes, there's a lot of content management software out there, but it's either specialized in some other area (mainly web applications, 'cause there's a lot of money to be made there) or it's a general-purpose CMS platform that takes a lot o

  • Cheesy (Score:5, Funny)

    by Webmonger ( 24302 ) on Tuesday April 29, 2003 @12:30PM (#5835072) Homepage
    In a similar vein, Scott Abel has demonstrated how to use the same review [stcsig.org] for multiple audiences.

    Why not just submit a link, Scott? Sheesh.

  • ....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)

    by Junks Jerzey ( 54586 ) on Tuesday April 29, 2003 @12:32PM (#5835101)
    I guess we've all gotten used to artificially inflated monster technical books, where it's expected that Learn Java 2 in 24 Hours needs to be 950 pages or it's crap.

    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.
    • I've been told on multiple occasions that US authors get paid by weight rather than content. Anyone want to confirm or reject this?

      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/

      • > K & Ritchies ANSI C book sets a fine standard for concise technical books.

        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.

      • 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]/".

    • Ahmen. The most resourceful book on the planet for me is LEARN SQL IN 10 MINUTES. It has quick refferences to JOIN statements and whatnot. It's a whopping 208 pages :-D
      • I'm going to create my own series of books, called "Learn xxxxx in 27.3 seconds", where xxxxx is some really difficult, technical subject. Of course each book will have to be at least 500 pages!
    • Those big books are hugely padded by: ...

      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.
      • One of my prime criteria when buying technical tomes is ensuring that they didn't fill 2/3rd of the book full of "reference" type material (library function listings, etc). In the era of online help and resources, this is not only unnecessary, it's counter productive.
  • If you've ever used a program called InterLeaf you will understand that this is what publishing is all about.

    You create a content object and add it to your content library. Then, wherever you need that object, you point at it in the content library.

    For the HTTPd minded - it's the same idea as SSI.
  • The only thing this left out: what the hell is Single Sourcing?
    • Well, see, this review was written for the STC Single Source SIG newsletter. So, obviously, there was no need to define the term.
    • The Single-Source SIG (special interest group) of STC (Society for Technical Communication) defined single-sourcing as "using a single document source to generate multiple types of document outputs; workflows for creating multiple outputs from a document or database source."

      For more information:
      http://www.stcsig.org/ss/index.htm
  • The editors own and love this book. Just look at all the dupes posted. Same info again and again... (and in some cases, again and again...)

  • 246 pages, only? (Score:3, Funny)

    by G3ckoG33k ( 647276 ) on Tuesday April 29, 2003 @12:46PM (#5835253)
    Even if I have quite a few books on computer science, I still use www much more. It has far more than 246 pages and is near fully indexed through Google. And, cut'n'paste makes my life much more easier.

    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)

    by jeepliberty ( 624159 ) on Tuesday April 29, 2003 @12:52PM (#5835327) Homepage Journal
    Between small business environments and downsizing, engineers are now put in a position that requires them to document their software as well as providing operational and installation documentation.

    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.

    • I don't think anyone would dispute that the person that develops code shouldn't test it. The same is true for documentation, for some of the same reasons.

      However, I agree, developers can, and should, contribute to helping users, especially through forums and blogs. Steve Muench does a great job on that at his website "Dive Into BC4J" [weblogs.com].

      BTW, the book being reviewed isn't really about writing documentation, it's about managing documentation projects, with some writing guidelines for creating modular do

    • Blockquoth the poster:

      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.

      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

      • Exactly what I have found. They are lost in the trees and can't see the forest.

        They know the product (code or hardware) so well that they forget some of the preliminaries, and the stuff they produce is not task oriented. A cookbook produced by a similar method would have the titles for all the recipes listed together, all the ingredients in another place, all the mixing instructions together, all the cooking instructions listed together. Actually cooking something would require that you consult severa

  • turning point? (Score:5, Interesting)

    by voixderaison ( 665336 ) on Tuesday April 29, 2003 @12:58PM (#5835373) Homepage
    This review was stimulating, and filled me briefly with hope, then I crashed after pondering a bit. I'd like to think that we could look back on this someday as a turning point of some sort, perhaps the foundation of a new engineering discipline of documentation. Of course, lots of people thought (and probably still do) that SGML was the foundation and now we're building walls. And maybe it was, but SGML (and the derivatives HTML, XML, and future arbitrary useful DTD to come) suffer from some problems - external and cultural mostly. The technologies are somewhat complex, and there is a general lack of understanding about how to apply the technology to advantage.

    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)

      by jolshefsky ( 560014 )
      Just to spin what you've said--I think it's very sad that the organization of information is the afterthought in most documentation projects. The first question everyone seems to have is, "should command names be in Courier or Arial?" Come on ... if you're staring at the prospect of handling some quantity of information equivalent to (at a minimum) hundreds of pages of printed text, don't you think it should be your first priority to get a handle on how to organize that information?

      I'm mired deep in tha

      • You could ditch template wars by insisting everyone in your organisation uses an industry standard. Try DocBook [docbook.org], an SGML standard for authoring technical documenation. I've used this for a number of years, knowing the information I'm producing will be processable in years to come. It's scaleable to huge numbers of large documents, so with that covered, you can go back to arguing about which fonts to use for command names ;)
    • What you've just described ("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") has been the holy grail for development/documentation teams for a number of years now.

      But earlier, you called for an investment in skilled technical writers. The fact that you even remember when a tech writer was assigned to every project (mostly because the mainframe programmers had no time or skills for such nonsense) shou
  • RUP is a giant, modularized HTML/applet documentation system. It is designed to be customized to projects, and can accept plug-ins.
    RUP Link [rational.com]

    Also, the cobination of SoDA, Rose and Requisite Pro offer a lot of options for manipulating requirements and code documentation.
    ReqPro Link [rational.com]

    (If this seems like an ad... I work work for IBM Rational.)

    • " RUP is a giant, modularized HTML/applet documentation system"

      And how does that help the quality of the CONTENTS?

    • Out of curiosity, why is it that any time I've ever tried to find out what this Rational Unified Process is all about, it ALL sounds like some big advertisement geared towards clueless management folk? Is it really all that great? Can somebody explain it in hacker terms? That shite makes my eyes glaze over.
      • In hacker terms ... it's a pain in the ass to use, but PHBs like the idea and the sales staff convince them that it will make the project flow better.

        It does code check in and out, but so do other tools.

        It did make it possible to make sure we had all the requirements tested and passed (but a simple spreadsheet or bug reporter could have done the same thing). Unfortunately its tendency to blow up and trash documents unless the editing was done in a certain not-quite-documented sequence makes the thought

      • RUP is a development process framework. It's sold as a bunch of documents/templates/intranet stuff, at a pretty eye-watering price. What's a development process framework ? It's a way of saying "when you start a software project, you usually need to go through a bunch of stages. For each of these stages, we have templates/guidelines/documents blah to help you build non-code artifacts (project plans, requirements documents, release notes, the whole kit & caboodle). Customize this to your organisation/pro

  • The whole challenge of single-sourcing isn't in which technologies to use, but the integration of these technologies, the process by which content is produced and the interaction between content (knowledge) producers.

    For example, at my last company we wrote software products. Document engineers would typically take one of the (almost) finished products and start writing documentation from scratch. Technical information that was already stored in programs, on wikis, in configuration files, etc.. was dupli

  • I would find these reviews a lot more useful if there was more disclosure of the reviewers biases.

    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
    • I am, admittedly, biased. Why? I believe in single sourcing, have participated in successful single sourcing initiatives and think the book is great. It's simple and straightforeward. What's not to like?

      I don't know the author personally, nor am I employed by the author, etc. I just like the fact that someone FINALLY has written a book on the topic -- and done it well.

  • Excuses.... (Score:3, Funny)

    by Jace of Fuse! ( 72042 ) on Tuesday April 29, 2003 @03:08PM (#5836719) Homepage
    "Honest officer, I was just eating a can of pringles and I thought, 'Hey! Maybe someone provides free internet service outside this large office building!'"

  • Single sourceing: Tech Writing's Newest Boondoggle (Score:3, Interesting)

    by tres ( 151637 ) on Tuesday April 29, 2003 @05:14PM (#5837890) Homepage
    Sorry, I've seen first hand "single sourcing" hard at work. It's the biggest boondoggle since the "synergies" of the late nineties.

    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.

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

      I benefit from single sourcing. No, it doesn't directly make my books more effective, but it does mean I spend a little less time replicating changes all over the place, so I have that much more time to spend on more direct improvements to the books.

      It's not a "magic bullet," and won't even help at all in certain situat

      • The thing about "single sourcing" is that people have been doing it for years. It's just never had the high-prestige and high price tag that it has today.

        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
    • And what really suckjs is that it's not even a NEW boondoggle. I've been hearing about the promised land of single source documents for at least a decade. Anyone remember "Information Mapping" with its expensive seminars and rigid templates? Where are they now?
  • I am glad to see another emerging IT "area" in which all the tools and consultants can be replaced by a set of simple Perl scripts.
    (pod2man, pod2html, etc.)

Slashdot Top Deals

Saliva causes cancer, but only if swallowed in small amounts over a long period of time. -- George Carlin

Close