RE: [BULK] Re: Coding documentation?

Subject: RE: [BULK] Re: Coding documentation?
From: Mike McCallister <mike -dot- mccallister -at- pkware -dot- com>
To: Hannah Drake <hannah -at- formulatrix -dot- com>
Date: Wed, 4 Dec 2013 20:44:31 +0000

Hannah,

We use part numbers for our mainframe product docs. Here's an example of our convention:

Part: SZZU- V150R0001

Translation:
SZ = Product (SecureZIP)
Z = z/OS (IBM mainframe)
U = User Guide (one of five manuals that come with each product)
After the hyphen: Version 15.0, Release (aka Levelset) 1. We refer to this internally as v15.0.1. Versions are annual (more or less). Levelsets come out a few times a year.

Hope this helps...

Mike


Mike McCallister
Senior Document Architect



PKWARE, Inc.
648 N. Plankinton Avenue
Suite 220
Milwaukee, WI 53203
Direct: 414-289-9788 x1136
www.pkware.com

SecureZIP Reader is now available on Apple® iTunes® and Google Play! 





-----Original Message-----
From: techwr-l-bounces+mike -dot- mccallister=pkware -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+mike -dot- mccallister=pkware -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Hannah Drake
Sent: Wednesday, December 04, 2013 1:54 PM
To: Haim Roman
Cc: TECHWR-L (techwr-l -at- lists -dot- techwr-l -dot- com)
Subject: [BULK] Re: Coding documentation?
Importance: Low

Excellent responses. Are there any conventions anyone could suggest?


On Wed, Dec 4, 2013 at 2:46 PM, Haim Roman <haim -dot- roman -at- gmail -dot- com> wrote:

> punctuation can be useful in breaking up long numbers. E.g., I often
> put dashes in phone numbers.
> That said, Dan brings an excellent example of unnecessary punctuation.
>
> -- Howard (Haim) Roman
>
>
>
> On Wed, Dec 4, 2013 at 9:40 PM, Dan Goldstein
> <DGoldstein -at- cytomedix -dot- com
> >wrote:
>
> > Some initial thoughts:
> >
> > Avoid unnecessary strings of zeros ("P/N 1350000056").
> > Avoid unnecessary punctuation ("P/N 135-678.90-2/4").
> > If you use lettered prefixes ("P/N QT75729A2"), keep the prefix
> > chart as brief as possible.
> > Avoid using letters that can be confused with numbers (O for 0, I
> > for 1, etc.).
> > Never use case-sensitive letters (e.g., QT75729A2 and qt75729a2
> > should be the same document).
> > Use a consistent method for distinguishing releases from drafts:
> > letters in suffixes, numbers in suffixes, dates in suffixes, etc.
> > Ask as many people as possible to review the system before you
> > implement it. Ignore anyone who finds a way to complicate the
> > proposed system, and worship anyone who finds a way to simplify it.
> >
> >
> > -----Original Message-----
> > From: Hannah Drake
> > Sent: Wednesday, December 04, 2013 2:17 PM
> > To: techwr-l
> > Subject: Coding documentation?
> >
> > Hi TechWrl Family,
> >
> > (I'm loving this list by the way) -- Now that my company has started
> > to grow a library of professional documentation, someone suggested
> > assigning part numbers to the documentation instead of just the date
> > it was
> released.
> > But, the convention they use for our part numbers doesn't quite work
> > for documentation.
> >
> > What numbering conventions can you suggest? Right now I just keep
> > the latest version of something on our Google wiki, which has a
> > version history, so that sort of works. But I feel like it would
> > look more
> polished
> > if we started using some fancy, "no idea what that number means --
> > QT75729A2 is so mysterious" numbering system.
> >
> >
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> > authoring.
> >
> > Learn more: http://bit.ly/ZeOZeQ
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as haim -dot- roman -at- gmail -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources
> > and info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our
> > public email archives @ http://techwr-l.com/archives
> >
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> authoring.
>
> Learn more: http://bit.ly/ZeOZeQ
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as hannah -dot- drake -at- formulatrix -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources
> and info.
>
> Looking for articles on Technical Communications? Head over to our
> online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our
> public email archives @ http://techwr-l.com/archives
>



--
Hannah L. Drake
Lead Technical Documentation Specialist
Formulatrix, Inc.

781-788-0228 x137 (office)
617-610-6456 (cell)
hannah.drake.formulatrix (skype)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as mike -dot- mccallister -at- pkware -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Coding documentation?: From: Hannah Drake
RE: Coding documentation?: From: Dan Goldstein
Re: Coding documentation?: From: Haim Roman
Re: Coding documentation?: From: Hannah Drake

Previous by Author: RE: [BULK] Re: On the value of glossaries containing terms the audience should already know
Next by Author: RE: [BULK] Re: On the value of glossaries containing terms the audience should already know
Previous by Thread: Re: Coding documentation?
Next by Thread: Re: Coding documentation?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads