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.
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
documentation.
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
Thailand
Mobile: 0853349635
Technical Writing
Help Guides | Tutorials | User Manuals http://dl.dropbox.com/u/14906355/hiretech_write.htm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?
