[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Your replies to Modular Documentation
On 8 Feb 2002, at 16:44, Ed Manley wrote: > I would like to take a set of three of the documents that I typically create > for an enhancement; a Functional Specification, a Technical Specification > and a section extracted from our User Guide, to learn how to do MDM. > > I chose these three because they are all extensions of the other - my FS is > basically an intro, a requirements list (I know, I know...we are looking for > a tool) and sections containing descriptions and specifications for the > enhancement, at the functional level, including screen shots, tables, file > layouts, whatever... > > The TS takes almost that exact structure down to the technical level, > reusing most elements and expanding on some. > > Then, the User Guide takes info from the FS and TS, literally a > copy-and-past operation for screen shots and certain text, button > click-events, business rules, user actions and so on. Ed, it sounds like you are well on the way. In my experience, the hardest part of MDM is designing the structure of the documents before sitting down to write. Think of the process in the way an architect designs a building: start with a foundation, build a framework on top of it, finish out the frame, and then add the trimmings. In traditional SGML circles, the work of creating the foundation is called document analysis. Brian Travis (http://www.architag.com/) and Ginny Redish (http://www.redish.net/) have written some articles about this type of approach, which is essential to a successful MDM implementation. You can also look at the Information Mapping technique, which might also help. > So, we could boil these three documents down to a number of reused sections. > In fact, these documents are usually created by cutting an element from one, > pasting it into the next, and perhaps expanding upon it. Of course, many > enhancements may affect that same screen shot, in different sets of > documents; That's why the same screen shot might easily exist in fifty > documents, each shot a different color and size and most likely a different > release version! Seems to me to be a perfect trial for MDM. > > So. Anyone care to offer their complete and detailed ideas on how to go > about it? My best advice is to worry about the tools until later. If you are hell-bent on using XML, there is a learning curve, which may or may not distract you from the larger goal: doing MDM. Of course, gaining knowledge about the toolset can also inform your work efforts. In this sense, it may make sense for you to hire a consultant to help out on the technology side. It depends on the timeline for your project and your own interest in learning the various tools. As a final thought, if you want a true guerilla approach, try the following: 1. Take your documents and print each type of document on a different color of paper. For example, print the Functional Specification on light blue, the Technical Specification on pink, and the User Guide on yellow. Take a pair of sissors and cut out the parts of the documents that appear in other documents. With this simple paper model, you can start to rearrange the contents and get a better picture of the information flow between the various documents. This gives you the bird's eye view of the territory and is also much easier to do than modelling the whole thing in a DTD or a database. 2. For each document type, highlight the sections that are important for each type as well as the boilerplate text that appears in the document. For example: the books I write always have a preface that contains a section called "Typographical Conventions". The information in this section is the same throughout each book. This is what I call a one-to-many modular documentation approach: a standardized section is written once and reused in various publications. By looking at the reusable content within a book, you can determine whether it is possible to reuse information on a global scale (such as the above example) or on a local scale. For example, all user guides must have the same sections in an initial introduction chapter. 3. At this point, you have to look at how you can implement your models using some type of technology. One approach is to use the master document feature of MS Word; another approach is to learn DocBook and try to model your documents using its syntax. For example, in DocBook, you can take two approaches to sections: numbered sections (<sect1/> and <sect2/>) or recursive sections (<section/>). I have found that recursive sections are much easier to use when doing MDM since I do not have to retag sections if I alter or change the structure of the document. I realize this is a long-winded reply but I hope it helps a bit. Feel free to contact me offlist, if you would like to discuss MDM approaches in more detail. [:>) "It is difficult to get a man to understand something when his salary depends on his not understanding it." Upton Sinclair
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC