TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
