PERILLO@hulk.cisco.com (Fran Perillo) (09/18/90)
Simon, >> Why the heck has cisco started to make their release notes absolutely >> useless? Why do I need a complete new manual for each software release? >> (Money is not a problem, but throwing away a complete set of manuals >> every three to four months, is in my eyes complete nonsense and seriously >> discredits cisco in my opinion.) >> I've had three TRouters upgraded from various software releases to 8.1, >> what I want is a list of changes from the 8.0 docs (which I have) to >> 8.1 (the release notes provide this) and how to use the new features >> (the release note do NOT help in this respect). We have made some significant changes to the documentation structure and this may not have been communicated to everyone. I will discuss the Gateway System Manual and the Terminal Server Manuals separately (since you have TRouters, you have both of these manuals). Since 1988, we have produced a total of two "completely new" Gateway System Manuals (order numbers DOC-G1 and DOC-G2), and have released a total of six major software releases. Each software release spanning this time was documented into what we called "Release Notes" (probably misnamed). You may recall that, as the number of new features increased, so did this Release Note, and it came to be larger than the 1988 manual itself! DOC-G2, or the 8.1 Release Gateway Manual, was completed in May and was a major step toward incorporating the release notes into the manual itself. For this release, we felt it was very important to provide all the information in a single document. We merged material from the old gateway manual (DOC-G1, 1988) as well as the most current 8.0 release notes to produce this new manual. The release note changed at that point to provide you with an overview of the new release. Items we cover include available features, modifications, caveats, version levels and how to install the new software. These release notes will continue to accompany each software release, maintenance or otherwise. All succeeding maintenance releases are documented via updates or errata pages and include an updated release note for that particular release. The same manual text is shipped with a release note and updates or errata pages. Now on to the Terminal Server Manual. We produced one in 1988 and, as with the Gateway Manual, we updated that manual through the "Release Note". In January 1990 we revised the Terminal Server Manual to coincide with the introduction of 8.0, and since then have issued update pages for the 8.1 features (introduced in May). If you ordered a terminal server since May, you would have received the January 1990 manual with the update pages and the newer version release note. New material for manuals is handled in a couple of different ways, depending on the extent of the information, the type of release, etc. We have been producing feature-rich releases, and the documentation effort is substantial. When new documentation is almost as large as the current manual, I believe we are correct in deciding to revise the manual. To recap, here are the ways in which documentation is released: -- UPDATE PAGES are used when a complete manual revision is not necessary but significant changes to information have occurred. Update pages are those which you described: complete manual replacement pages, three-hole punched and ready to insert in the correct location in the manual. A page of explanation would also be included. -- ERRATA SHEETS are used when there are errors or information missing from the document. The purpose of the errata sheet is to clarify misinformation; the life of errata sheets is very limited, lasting only until this information can be incorporated into the manual through either update pages or a complete revision. At that point the errata sheet is eliminated. Errata sheets are used as a quick temporary solution and when update replacement pages are not a viable option. It is intended that the user make note of the listed changes on the appropriate page in his manual. -- Complete Manual REVISIONS occur with each major software release or when the amount of new/changed information exceeds the percentage suggested for using update pages. A manual revision consists of issuing a completely new document. Reorganization and rewriting may also occur during this cycle. I hope these descriptions help to explain the process we go through and the reasons behind our decisions. Thanks for taking the time to send us your comments. Francine Perillo, cisco Customer Documentation Manager -------
fortinp@bwdls56.bnr.ca (Pierre Fortin) (09/21/90)
In article <26412@boulder.Colorado.EDU>, PERILLO@hulk.cisco.com (Fran Perillo) writes: > the manual. > > To recap, here are the ways in which documentation is released: > > -- UPDATE PAGES are used when a complete manual revision is not necessary > but significant changes to information have occurred. Update pages are > those which you described: complete manual replacement pages, three-hole > punched and ready to insert in the correct location in the manual. A > page of explanation would also be included. > > -- ERRATA SHEETS are used when there are errors or information missing > from the document. The purpose of the errata sheet is to clarify > misinformation; the life of errata sheets is very limited, lasting only > until this information can be incorporated into the manual through either > update pages or a complete revision. At that point the errata sheet is > eliminated. Errata sheets are used as a quick temporary solution and > when update replacement pages are not a viable option. It is > intended that the user make note of the listed changes on the > appropriate page in his manual. > Are either of these sent, as they are released, to your customer base? I have never received UPDATE/ERRATA stuff separately. > -- Complete Manual REVISIONS occur with each major software release or when > the amount of new/changed information exceeds the percentage suggested > for using update pages. A manual revision consists of issuing a > completely new document. Reorganization and rewriting may also > occur during this cycle. > Any chance we could get electronic copies (PostScript is fine) from your ftp machine? With now over 65 LOCATIONS (I've lost count of the number of routers) on our main network, getting the manuals electronically for local printing would make life much easier for both of us. We would ftp only once from cisco and distribute internally if this was available. > > Thanks for taking the time to send us your comments. > > Francine Perillo, > cisco Customer Documentation Manager > ------- Thanks for great support... Cheers, Pierre Fortin fortinp@bnr.ca