Documentation : Naming Standards
Halon5
Enthusiast ✭✭
in Water Cooler
We are trying to work through the GMS 9.2 Documentation but it is difficult to follow.
NORMALLY we would expect to see Version Numbers in the "File Name".
NORMALLY We would also see the version number in the footer of every page
NORMALLY We would see the version number on the Title Page.
The GMS 9.2 Documentation "Sections" seem to have been split into separate documents. WHY?
Please Fix.
Category: Water Cooler
0
Comments
It's easier to answer the last question first. The GMS was getting very large and hard to manage, and some noted that it was difficult to find data in such a large document. Also not everyone uses all of the features. We split the information in smaller chunks to make the information more usable and accessible, but it also gave us the benefit of being able to only update the documents that needed updating when revisions were required. Smaller books are easier to update quickly. To support the idea of only some documents being updated with each release, we needed to revamp our naming and tracking convention. We didn't want to confuse people by showing a doc set where some books were labeled with 9.1 and others had 9.2 on them them, but content was still current and correct in all. Based on your comments, it looks like we need to go back to the drawing board on that one and reassess our labeling. Thanks for your feedback. We'll tackle that in our upcoming update for that document set.
Hi @LynS
SonicWALL could also do with some need some kind of bibliography given the number of documents across all product sets.
The stand out for me over some 40 years was always IBM manuals. They have always been the best at it IMHO. In the day there were also update pages sent so you could update your hard copy manuals.
So while we are at it there should also be a PUBLISHED DATE. And then there was an UPDATED DATE as I recall on the inside cover. these things were being done as far back as in the 80's. This would fix some of the issues you have raised?
Here is a sample : -
Best to your efforts.
Stephan.
I'd like to also comment on the documentation.
I did a search for CSC - nothing. Cloud GMS - nothing. The fully spelled out Capture Security Center - and still nothing.
At the very least I would expect 1 hit. At the most, I would expect a full category on the left-hand side of the page.
Here's hoping someone can adjust that...
Hi @Larry @LynS
Thanks for your input.
As with all REFERENCES and GUIDE documents. Those things should be found in the INDEX. In a Bibliography you might also find those items, pointing to the documents in which you may find them.
These documents should also have of course CONTENTS, FIGURE references etc..
..And wouldn't it be FANTASTIC if we could find the correct version documents contained with the code downloads.
While there are some great things going around building on the bigger things at SWL, It's often the little things that count to creating a quality solution.
My 2 cents..
--Steph.
@Halon5 - off topic (slightly)
I am pleased that you referenced IBM as having been a leader in the field of systems documentation. I broke my teeth in this industry by reading (and updating) those massive books. A brilliant colleague at the time said you had to read IBM doc three times: the first to get the gist of it, the second to answer your questions, and the third to begin understanding what you were supposed to be doing.
In 2001, I got my chance to fulfull a professional dream: I went to San Jose for three months and became co-author of an IBM Red Book. Two years later, I went back and did it again.
Of course, 20 years later, I really hate writing my own Standard Operating Procedures, but that's another story...
But I do want SonicWall to have a searchable documentation index that allows anyone to find information about their latest products. It would also behoove them to have the kind of cross-referencing of information about which product releases are included. Not so sure I need to see revision marks on the borders, though...
Hiya @Larry ,
You sound like a kindred spirit. LOL.
I sure loved IBM manuals. I recall breaking the plastic wrapper and enjoying the smell of that brand new manual inside.
My first computer in '79 looked like this. An IBM 360/40. I worked on so many, through the 4300 series and so on.. plug compatibles and the like. IBM operating systems like IBM's VSE / VM / MVS and supporting online telecommunications systems and file management like CICS / VTAM / NCP/VSAM /DFDSS/ DFHSM.....and the like (so lots and lots of manuals - like a large library. I sure miss all that stuff.
The REDBOOKS which came later were a great "cookbook" resource and have been ever since.