Join the Conversation

To sign in, use your existing MySonicWall account. To create a free MySonicWall account click "Register".

Documentation : Naming Standards

Halon5Halon5 Enthusiast ✭✭

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
Reply

Comments

  • LynSLynS SonicWall Employee

    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.

  • Halon5Halon5 Enthusiast ✭✭
    edited May 2020

    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.

  • LarryLarry All-Knowing Sage ✭✭✭✭

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

  • Halon5Halon5 Enthusiast ✭✭

    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.

  • LarryLarry All-Knowing Sage ✭✭✭✭

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

  • Halon5Halon5 Enthusiast ✭✭
    edited June 2020

    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.



Sign In or Register to comment.