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.
Subject:Re: Coding documentation? From:Hannah Drake <hannah -at- formulatrix -dot- com> To:Haim Roman <haim -dot- roman -at- gmail -dot- com> Date:Wed, 4 Dec 2013 14:54:22 -0500
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.
