Software documentation

Was looking for resources for writing software documentation for a friend (and for myself as well). Figured the STC would be the most authoritative resource. On the STC Four Lakes, Michigan site, I found their book list to be enough, but figured there must be some guidelines for writing documentation on the web. Anyone know any good freely available resources /guidelines for writing software documentation that might be available on the web?

Kristjan pointed out one we blogged from Advogato a while back: How non-programmers use documentation.

STC Usability SIG, Usability toolkit

The STC Usability SIG offers a collection of documents including forms, checklists, templates for conducting usability testing and user interviews.

Polar Bear II Review

James McNally has a great review of Information Architecture for the World Wide Web, Volume 2 to round up this month's IA-focused Digital Web Magazine.

To be completely honest, trying to give you a taste of the content of this book is going to be a little bit like trying to take a drink from a fire hose. ... Information Architecture for the World Wide Web is an introductory course in a discipline of which we are all slowly becoming practitioners. That it is such an enjoyable course is due entirely to the knowledge and experience of the authors. Their humility, evident in their willingness to point the reader to other sources of information, is also refreshing.

2003 IA Summit -- Call for Participation

The call for participation for the March 2003 IA Summit has gone out. They're looking for case studies and presentations, as well as posters. Deadlines? December 2, 2002 for case studies and presentations, and January 15, 2003 for posters. Follow the links for more info.

[Thanks, Digital Web Magazine.]

Polar Bears invade B & A

Boxes and Arrows is running an interview with Lou Rosenfeld and an excerpt from the new edition of the Polar Bear book that focuses on MSWeb (the Microsoft intranet).

Accessibility Arguments Revisited

New on Frontend Usability Infocentre.

    Regular Infocentre readers will know that Frontend has been arguing for the need for greater accessibility on the web for some time. Frontend have recently completed the delivery of the first version (1.1) of the Irish National Disability Authority (NDA) IT Accessibility Guidelines. In the course of our work for the NDA over the last year we've talked to a wide variety groups and individuals who have an interest in accessibility and as a result of their input, our approach has shifted a little. Here's what we found out.
UK Government & Metadata

Quick article on UK Government's use of metadata and thesaurus to support information management and organization.

"Keeping an eye on metadata" by Glyn Moody, August 8, 2002 from CW360.

TOC for the IA issue of JASIST

The table of contents is available for the Information Architecture issue of the Journal of the American Society for Information Science & Technology (JASIST). Full text is available to members who have opted for electronic access only.

New XML feed for Radio News Aggregators

Apparently there is some problem with Radio grabbing iaslash's newsfeed and showing duplicates. For Radio aggregator's here's the workaround for now. I am using lynx to dump the XML feed once a day. Source is here:
Thanks to Lee for pointing this out.

The Semantic Web: Taxonomies vs. ontologies

"The Semantic Web: Differentiating Between Taxonomies and Ontologies." Online. 26 n4 (July/August 2002): 20.

    Computer scientists--along with librarians--are working to solve problems of information retrieval and the exchange of knowledge between user groups. Ontologies or taxonomies are important to a number of computer scientists by facilitating the sharing and reuse of digital information.
Katherine Adams' article in ONLINE (ironically, not available online) talks about the Semantic Web and the subtle difference in the approaches that computer science and library information science have taken toward making information findable using structured hierarchical vocabularies -- ontologies for CS and taxonomies for LIS.

The article generalizes one difference between CS and LIS by saying that "software developers focus on the role ontologies play in the reuse and exchange of data while librarians construct taxonomies to help people locate and interpret information". Both hopefully remain focussed on the end result of making data findable and usable.

    Some of the traditional skills of librarianship--thesaurus construction, metadata design, and information organization--dovetail with this next stage of Web development. Librarians have the skills that computer scientists, entrepreneurs, and others are looking for when trying to envision the Semantic Web. However, fruitful exchange between these various communities depends on communication.
    Commonalities exist--as do differences--between librarians who create taxonomies and computer scientists who build ontologies. Mapping concepts, skills, and jargon between computer scientists and librarians encourages collaboration.
I'm quoting a few large blocks from the article because they're probably important for us to read (fair use!). One of the sections discussess differing views on inheritance and the last discusses topic maps.


    In general, those in computer science (CS) are concerned with how software and associated machines interact with ontologies. Librarians are concerned with how patrons retrieve information with the aid of taxonomies. Software developers and artificial intelligence scholars see hierarchies as logical structures that help machines make decisions, but for library science workers these information structures are about mapping out a topic for the benefit of patrons. For librarians, taxonomies are a way to facilitate certain types of information-seeking behavior. It would be a mistake to overemphasize this point since one can point to usability experts in the CS camp who advocate user-centered Web design or librarians who are fascinated with cataloging theory to the exclusion of flesh-and-blood patrons. Yet, as an overarching generalization, software developers focus on the role ontologies play in the reuse and exchange of data while librarians construct taxonomies to help people locate and interpret information.

    This difference is illustrated by the concept of inheritance. Computer scientists build hierarchies with an eye toward inheritance, one of the most powerful concepts in software development. Machines can correctly understand a number of relationships among entities by assigning properties to top classes and then assuming subclasses inherit these properties. For example, if Ricky Martin is a type of "Pop Star" in a hierarchy marked "Singers," then a software program can make assumptions about Mr. Martin even if the details of his biography are not explicitly known. An ontology may express the rule, "If an entertainer has an agent or a business manager and released an album last year, then assume he or she has a fan club." A program could then readily deduce, for example, that Ricky Martin has a fan club and process information accordingly. Inference rules give ontologies a lot of power. Software doesn't truly understand the meaning of any of this information, but inference rules allow computers to effectively use language in ways that are significant to the human users.

    By contrast, librarians think of inheritance in terms of hierarchical relationships and information retrieval for patrons. Taking the example above, the importance of the taxonomy rests in its ability to educate patrons. Someone who's been tuned out of popular culture might use the Pop Star hierarchy to learn the identities of singers who are currently in vogue. A searcher could also uncover the various types of Pop Stars that exist in mass culture: Singers, Movie Stars, Television Stars, Weight-Loss Gurus, Talk Show Hosts, etc. Finally, a patron could hop from one synonym to another--from "Singer" to "Warbler" to "Vocalist"--and discover associative relationships that exist within this category.


    Topic maps are closely related to the Semantic Web and point the way to the next stage of the Web's development. Topic maps hold out the promise of extending nimble-fingered distinctions to large collections of data. Topic maps are navigational aids that stand apart from the documents themselves. While topic maps do not include intelligent agents, other aspects of this technology--metadata, vocabularies, and hierarchies--fit well within the Semantic Web framework. According to Steve Pepper, senior information architect for Infostream in Oslo, Norway, in "The TAO of Topic Maps: Find the Way in the Age of Infoglut", his presentation at IDEAlliance's XML Europe 2000 conference, topic maps are important because they represent a new international standard (ISO 13250). Topic maps function as a super-sophisticated system of taxonomies, defining a group of subjects and then providing hypertext links to texts about these topics. Topic maps lay out a structured voca bulary and then point to documents about those topics. Even OCLC is looking to topic maps to help its project of organizing the Web by subject.

    An important advantage of topic maps is that Web documents do not have to be amended with metadata. While HTML metatags are embedded in the documents described, topic maps are information structures that stand apart from information resources. Topic maps can, therefore, be reused and shared between various organizations or user groups and hold great promise for digital libraries and enhanced knowledge navigation among diverse electronic information sources.

Other articles mentioned:
Tim Berners Lee, "The Semantic Web," Scientific American, May 200.

Natalya Fridman Noy and Deborah L. McGuinness. "Ontology Development 101: A Guide to Creating Your First Ontology," Knowledge Systems Laboratory Stanford University, March 2001.

Tom Gruber, "What is an Ontology," [September 2001].

Steve Pepper, "The TAO of Topic Maps: Find the Way in the Age of Infoglut," XML Europe 2000.

The Age of Information Architecture

In a new issue of Digital Web Magazine and a brand new column entitled IAnything Goes, Jeff Lash takes an in-depth look at just what is the big deal with IA: what it is, why it's needed, who should do it, and how it came about. The Age of Information Architecture. Also in this issue David Wertheimer writes about going Beyond the IA Guy: Defining information architecture in his Wide Open column.

Quick Visio Tips

Boxes and Arrows is running Three Visio Tips: Special Deliverables #4 from our favorite deliverables ninja Dan Brown. Quick, but good.

Thomas Vander Wal grooves on Maslow and information needs

Springing from Lou's post on splitting IA and IT, Thomas Vander Wal has an interesting piece on "Information Needs" reflecting Maslow's famed hierarchy.

Blogs as disruptive technology in the CMS industry

Was looking at News Blogging Software Roundup on the Microcontent News site. The article breaks weblogging applications into categories based on the type of publishing environment (weblog publishing or weblog community) and based on installation requirements. The page led to the Web Crimson white paper, Blogs as Disruptive Tech, which is an interesting piece that calls weblog publishing systems as disruptive to commercial content management systems as the PC was disruptive to the mainframe computer. Makes some interesting insights based on the ideas in Clayton Christensen book, "The Innovator's Dilemma".

The dilemma is this. Should CMS companies look at the current state of weblogging applications as a threat? It appears that the feedback from consumers is that weblogging applications are viable for many smaller publishing needs and are getting better at also meeting middle-range publishing and community communication needs. So much better that they may someday nip at the heels of mid-level CMS vendors and drive them out of business because of the free (or GPL) to really cheap pricing model that most follow. The improvement of simple web publishing CMSes and community tools such as the one used here has been very impressive considering the short life-time for this breed of software. I would think that CMS vendors make the same kind of calculations in their heads that mainframe salespersons made when they hear that there is a seemingly trivial application that customers are considering as alternatives to their large and very expensive systems. But is there an opportunity to generate revenue, however small, by offering lighter and much cheaper sytems as a reaction to the use of blogging tools in place of CMSes? I guess that's the innovators dilemma, do you heed or ignore the warning foretold in some consumer behavior.

Thanks Tom for the link to the Roundup article.

Whitepaper: The Importance of Information Architecture

Found over at Christina's, this whitepaper promises "Answers to the 10 most critical questions". Here's the blurb from the NavigationArts site

With the overwhelming quantity and demand for information, organizations are starting to think about the nature of their business's institutional knowledge, content and information and its increased burden on today's organization to find an effective means of collection and distribution. To best meet this need, information architecture helps to organize, prioritize and manage the generation, capture and distribution of information. This white paper addresses the ten most critical questions about information architecture in respect to its value in today's evolving business environment.

There's a rumor that dan wrote it, but I'm not sure which dan that exactly is. but I'll guess this Dan...if I'm wrong, let me know in the comments.

IA, usability, controlled vocabularies, findability and more.

Digital Web Magazine interviews Jeffrey Veen and Jesse James Garrett of Adaptive Path and Christina Wodtke writes about using controlled vocabularies to improve findability in Mind your phraseology!

Deliverables that Clarify, Focus, and Improve Design

From the 2002 UPA Conference comes Deliverables that Clarify, Focus, and Improve Design, a presentation and examples by Richard Fulcher, Bryce Glass and Matt Leacock.

The representations we choose for UI design affect both how we think about the design and how others understand it. Concept maps, wireframes, storyboards, and flow-maps speak to different audiences at different stages of the development cycle. This presentation provides examples of these documents and a toolkit for producing them.

There are a number of good downloads, but I especially liked the Key Relationships Between Design Deliverables (PDF), which is quite worthy of hanging up by your workstation. (Thanks to this article on Boxes and Arrows for the conference summary and link.)

Why Web Standards Matter

Carrie Bickner, web developer for the New York Public Libraries, has an article in Library Journal, Summer2002 Net Connect, that discusses how using W3C XHTML and CSS standards will ensure the accessibility of your data and may possibly save your organization time and money in future development and redesign.

    You've just launched your library's new web site when the calls start: "I just downloaded the latest version of Netscape, and your whole top navigation is invisible"; "I am using a screen reader, and your site reads like gibberish. I can't find a thing"; "I am calling on behalf of the board of tri-county library consortium; we appreciate all the hard work that you have done, but we have a few questions about the design of the new site."

    The site--despite months of work, the best software, and exhaustive quality assurance testing--has problems. What went wrong? How do you remedy the situation while insuring you don't make the same mistakes again? The key may be found in adhering to a set of well-established, internationally recognized web standards.

Internet Librarian 2002

The preliminary program is set for Internet Librarian 2002 (“The Internet Conference and Exhibition for Librarians and Information Managers”), being held November 4-6 in Palm Springs, CA. It looks like there are a lot of good sessions, with tracks and presentations on Intranets, weblogs, UCD, DRM, web writing, e-learning, searching, and the wireless web among other things.

Of particular interest was the description of The IA Divide: Issues Worth Fighting About, which features our very own Peter Morville and Peter Merholz:

Sometimes, it's the things we can't agree on that make life most interesting. In this spirited debate, the two Peters shine the spotlight on the most controversial and critical issues faced by information architects today. While they've got the same first names, these two experts have no problem finding differences. Come watch the battle, as Good Peter faces off against Bad Peter. And be prepared to pick sides. Audience participation and a sense of humor are required.

I'm picturing a cage match complete with folding chairs, easily-breakable tables, and concealed chokers...

XHTML 2.0 and the nl element

XHTML working draft 2.0 is here.

Hmmm. Am curious to see how w3c envisions the new navigation list (nl, same family as ul) element to work. Perhaps browsers will make the nl element collapsible/expandable like aqtree.

XML feed