RE: Principles, practices, and patterns approach to writing style guides? (was: Writing guides)

Subject: RE: Principles, practices, and patterns approach to writing style guides? (was: Writing guides)
From: Kelley Walker <kelley -dot- walker -at- libtax -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 21 Aug 2012 12:56:54 -0400

Yes. Thanks Kathleen!

I'm thinking about the classic reference cited in most design pattern books: Christopher Alexander's book, _A Pattern Language: Towns, Buildings, Construction_. Subsequently, this approach has been used by software developers in books like _Design Patterns: Elements of Reusable Object-Oriented Software_. In the UX field, Jennifer Tidwell pioneered the approach with _ Designing Interfaces_.

I've decided to use this approach to develop our in-house content development style guide.

I figured that there has got to be someone already employing this approach - even if it's an in-house approach. It would be a great topic for an STC panel at any rate! I'm thinking I should probably prowl conference proceedings and archives for someone who's written on the topic.

Kelley

> -----Original Message-----
> From: Kathleen MacDowell [mailto:kathleen -dot- eamd -at- gmail -dot- com]
> Sent: Friday, August 17, 2012 6:30 PM
> To: Kelley Walker
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Principles, practices, and patterns approach to writing style
> guides? (was: Writing guides)
>
> Interesting question, Kelley. I'm a technical writer with an abiding interest in
> UX. In fact, I know many tech writers are, at least to the point of being
> concerned about consistency in the user interfaces we document.
>
> I don't recall ever finding anything specifically aimed to writing.
> What I've done is keep an eye on UX publications; it seems to me that a lot of
> the information there is relevant to writing as much as to websites, Help, etc.
>
> Some other things I think are important when writing material (so far as
> usability for the customer). These are really basic tenets of good technical
> writing.
> organization
> clarity
> organization
> active voice
> organization
> topic driven (which translates well for those working with help systems)
> organization references (within the doc) organization illustrations and
> examples, where possible
>
> A while ago I was a member/volunteer of the STC Usability and User
> Experience SIG, and we reviewed some UUX books. You might check them
> out to see if they've added anything. I'm not sure what the current address
> of the SIG is, all my links seem to go to older versions of the site, but I can
> find out if you need it.
> Also, there's the UPA/UXPA, but I'm sure you know about them.
> http://www.usabilityprofessionals.org/
>
> Please post to the list if you find anything specific!
>
> Regards,
>
> Kathleen
>
>
> On Fri, Aug 17, 2012 at 4:41 PM, Kelley Walker <kelley -dot- walker -at- libtax -dot- com>
> wrote:
> > Hi there -
> >
> > Speaking of writing guides, I'm a UX Architect tasked with developing style
> guidelines that developers will actually use and to do so for all aspects of the
> user experience - from the user interface guidelines for software engineers
> to a manual of writing style for content developers.
> >
> > I laughed when I took this position. User experience practitioners write UI
> style guides and the like all the time, but I've seldom seen much published
> about how to make documentation usable. Of course, I'm hoping that
> technical writers will know about resources with which I'm not familiar.
> >
> > At any rate, I've decided to draw on MMOS, 4th ed., and then supplement
> with our company style guidelines by employing the principles, practices, and
> patterns approach that is common to software engineering.
> >
> > Does anyone know if anyone has done this for a writing style guide? If so, is
> there a published, publicly accessible example?
> >
> > On an old home days note, I used to belong to the list years ago.
> > What ever happened to Andrew Plato? :)
> >
> >
> > Kelley Walker
> > UX Architect
> >
> >
> > This electronic communication and any files transmitted with it, or attached
> to it, are confidential and are intended solely for the use of the individual or
> entity to whom it is addressed and may contain information that is
> confidential, legally privileged, protected by privacy laws, or otherwise
> restricted from disclosure to anyone else. If you are not the intended
> recipient or the person responsible for delivering the e-mail to the intended
> recipient, be advised that you have received this e-mail in error, and that any
> use, dissemination, forwarding, printing, or copying of this e-mail is strictly
> prohibited. If you received this e-mail in error, please return the e-mail to the
> sender, delete it from your computer and destroy any printed copy of it.
> Although our company attempts to sweep e-mail and attachments for
> viruses, it does not guarantee that either are virus-free and accepts no
> liability for any damage sustained as a result of viruses.
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Create and publish documentation through multiple channels with Doc-To-
> Help. Choose your authoring formats and get any output you may need.
> >
> > Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
> >
> > http://bit.ly/doc-to-help
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as kathleen -dot- eamd -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
>
>
>
> --
> Kathleen MacDowell
> kathleen -dot- eamd -at- gmail -dot- com

This electronic communication and any files transmitted with it, or attached to it, are confidential and are intended solely for the use of the individual or entity to whom it is addressed and may contain information that is confidential, legally privileged, protected by privacy laws, or otherwise restricted from disclosure to anyone else. If you are not the intended recipient or the person responsible for delivering the e-mail to the intended recipient, be advised that you have received this e-mail in error, and that any use, dissemination, forwarding, printing, or copying of this e-mail is strictly prohibited. If you received this e-mail in error, please return the e-mail to the sender, delete it from your computer and destroy any printed copy of it. Although our company attempts to sweep e-mail and attachments for viruses, it does not guarantee that either are virus-free and accepts no liability for any damage sustained as a result of viruses.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.

http://bit.ly/doc-to-help

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

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:
Principles, practices, and patterns approach to writing style guides? (was: Writing guides): From: Kelley Walker
Re: Principles, practices, and patterns approach to writing style guides? (was: Writing guides): From: Kathleen MacDowell

Previous by Author: Principles, practices, and patterns approach to writing style guides? (was: Writing guides)
Next by Author: RE: document design: I don't know what I don't know
Previous by Thread: Re: Principles, practices, and patterns approach to writing style guides? (was: Writing guides)
Next by Thread: Re: Principles, practices, and patterns approach to writing style guides? (was: Writing guides)


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

Sponsored Ads


Sponsored Ads