Re: An interview question

Subject: Re: An interview question
From: phil stokes <philstokes03 -at- googlemail -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 29 Mar 2013 22:35:02 +0700

You missed the point. I was drawing out an irony between talking about
'good documentation' in a document that is, itself, an example of poor

Perhaps I shouldn't have tried to pull that off on a Fridayâ ;)

To take you up on your own point, there's no reason why code documentation
is exempt from the same standards of clarity as any other kind of
documentation. With the exception that comments are also written for one's
own use, generally they need to be just as clear to a third party reader as
any other piece of text.

On 29 March 2013 22:21, Combs, Richard <richard -dot- combs -at- polycom -dot- com> wrote:

> phil stokes wrote:
> > Hmm, interesting point. In one of those moments of synchronicity, I just
> > happened to read an Apple doc this afternoon that ironically stated,
> among
> > other things, that:
> >
> > A principal goal of object-oriented programming is to make the code you
> > write as reusable as possibleâ.Reusability is influenced by factors such
> as
> > these:
> >
> > <snip>
> > ***How clear the documentation is***
> >
> > <snip>
> >
> >
> >
> > I say "ironically" as Apple docs are about as frustrating as any docs
> I've
> > ever read. With the exception of comprehensiveness, in any other terms,
> > their work falls so far below professional standards of good technical
> > writing it beggars belief.
> In the context of programming, "documentation" refers to documentation of
> the code, e.g., code comments, unit tests, maybe other software development
> artifacts. Reusability of code has nothing to do with end user documents.
> Richard G. Combs
> Senior Technical Writer
> Polycom, Inc.
> richardDOTcombs AT polycomDOTcom
> 303-223-5111
> ------
> rgcombs AT gmailDOTcom
> 303-903-6372
> ------

Phil Stokes
Language Instructor
Chulalongkorn University Language Institute
Phaya Thai Road, Patumwan
Bangkok, 10330
Mobile: 0853349635

Technical Writing
Help Guides | Tutorials | User Manuals
From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?

Learn more:


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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

An interview question: From: Peter Neilson
Re: An interview question: From: phil stokes
RE: An interview question: From: Combs, Richard

Previous by Author: Re: An interview question
Next by Author: Commenting Code (was Re: An interview question)
Previous by Thread: RE: An interview question
Next by Thread: Re: An interview question

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

Sponsored Ads