 |
BorlandTalk.com
Borland discussion newsgroups
|
| View previous topic :: View next topic |
| Author |
Message |
Charles Line
Guest
|
 Posted: Sat May 06, 2006 9:14 am Post subject: No wonder Borland Technical Documentation stinks |
 |
|
The job description for the technical writer vacancies at Borland show what
goes on behind the scenes and how documentation is really just a minor
sideshow in the whole process.
You can see it at:
http://borland.hodesiq.com/job_detail.asp?JobID=666131&user_id=
But the bits that jump out at me are:
"Research material without written technical specifications"
What does this mean? Are there swathes of material requiring documentation
that have no technical specifications? Is is a free-for-all?
"Produce clear, accurate, and well-organized documentation that requires
minimal editing with minimal direction"
Miminal editing and minimal direction, eh? I take that to mean that this
stuff is unlikely to be read within the organisation once it's been written
and that the QA within the technical documentation domain is "minimal" to
non-existent. I can imagine that somebody will look at the titles and if
everything on the checklist is there then it gets signed off.
The overall advert implies that what they are after is somebody who can
write stuff without any feedback from anybody. Somebody who has to read the
source code to figure out how to describe something rather than get adequate
input from the architects and implementors and somebody who can live with
nobody ever giving them any idea whether what they are doing is poor,
adequate or excellent.
In other words..
"Here's your desk. Here's the code. Now get on with it and I don't want to
hear from you again until it's finished"
This does not fill me with confidence, especially as the quality of
documentation is what causes me greatest frustration with what comes out of
Borland. |
|
| Back to top |
|
 |
Dave Jewell
Guest
|
| Posted: Sat May 06, 2006 10:14 am Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Charles Line"
<charles (AT) ihatespamwithpsychoticintensity (DOT) clsinternal.notthisbittakeitout.net>
wrote in message news:445c65ba (AT) newsgroups (DOT) borland.com...
| Quote: | "Research material without written technical specifications and read
source code to
create new documentation or update existing documentation.
|
The quality (or otherwise) of technical documentation is one issue, but for
me the real eyebrow-raiser is the implication that document writers have to
cope without proper technical specs and have to figure out how the source
code works in order to write the documentation. If true of documentation
writers, then it would also be true of new developers coming on the team,
and *that* would indeed be a free-for-all. Tell me it ain't so.... ;-)
Dave |
|
| Back to top |
|
|
Dave Nottage [TeamB]
Guest
|
| Posted: Sat May 06, 2006 11:14 am Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
Charles Line wrote:
| Quote: | Miminal editing and minimal direction, eh? I take that to mean that
this stuff is unlikely to be read within the organisation once it's
been written and that the QA within the technical documentation
domain is "minimal" to non-existent.
I can imagine that somebody will
look at the titles and if everything on the checklist is there then
it gets signed off.
|
It probably *is* just your imagination. How about asking, rather than
assuming the worst?
| Quote: | The overall advert implies that what they are after is somebody who
can write stuff without any feedback from anybody.
|
Strange how "minimal" becomes "none".
--
Dave Nottage [TeamB] |
|
| Back to top |
|
|
Bob Dawson
Guest
|
| Posted: Sat May 06, 2006 12:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Charles Line" wrote
mostly nonsense I'm afraid. Speaking as a developer with several years
experience as a professional tech writer, this is exactly the ad I want to
see from Borland.
| Quote: | "Research material without written technical specifications"
What does this mean? Are there swathes of material requiring documentation
that have no technical specifications? Is is a free-for-all?
|
It means the same for a technical writer as it would mean for a programmer:
that a very senior hire should be expected to be capable of greenfield
design and production, not just filling in and refactoring material that
others have already produced. Thas ad is for a TW 4 with 8+ years
experience. The person hired should be able to interact directly with the
lead code architects and analysts/developers and understand what they say
(which is that the ad says: "Collaborate with other team members, QA
engineers, R&D engineers, and Product Management"), and not expect things to
be handed to them.
| Quote: | "Produce clear, accurate, and well-organized documentation that requires
minimal editing with minimal direction"
|
Again, this is a tech writer IV position--a senior/leadership hire. Would
you prefer they hire someone who can't be trusted to produce production
quality work? Would you hire a senior/team-lead programmer who couldn't
produce production quality code without continual supervision and review?
| Quote: | In other words..
"Here's your desk. Here's the code. Now get on with it and I don't
want to hear from you again until it's finished"
|
Go back to the 'Collaborate..." sentence. You're making this stuff up. The
ad clearly says nothing of the kind.
And actually the ad description makes it look like DevCo is moving in the
right direction: towards agile development by cross-functional teams that
get tech writers and test engineers in working with R&D directly and from
the beginning. That's excellent.
| Quote: | This does not fill me with confidence, especially as the quality of
documentation is what causes me greatest frustration with what comes out
of
Borland.
|
Actually this is exactly the caliber person that Borland /should/ be hiring:
some one whou can come in to an agile team and be an impact player. And the
fact that they're advertising the position while making layoffs elsewhere
may indicate an increased sense of the importance of documentation. It's had
to see that as anything but good news.
bobD |
|
| Back to top |
|
|
Peter Morris [Droopy eyes
Guest
|
| Posted: Sat May 06, 2006 1:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
To me this says
"Take the code, write what it does" which is actually really nice work to
do. Just because you aren't given lots of guidance (maybe just a structure
outline) doesn't mean you have no other sources of information, considering
you are within the same company I'd imagine it is very easy to ask the
author of some new code "what does this do?".
This is exactly how I went about writing my document on ECO services. I
started with an outline, tested the behaviour using test apps, worked out
what it was doing + why, and then explained it. It was great fun!
--
Pete
====
Audio compression components, DIB graphics controls, ECO extensions,
FastStrings
http://www.droopyeyes.com
My blog
http://blogs.slcdug.org/petermorris/ |
|
| Back to top |
|
|
Felipe Monteiro de Carval
Guest
|
| Posted: Sat May 06, 2006 1:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
I find my Delphi (D5) documentation really good.
Acctually I even used it to learn programming!
--
Felipe |
|
| Back to top |
|
|
Atle Smelvær
Guest
|
| Posted: Sat May 06, 2006 1:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
Spot on :)
Nice to see a constructive and good post in here.
-Atle |
|
| Back to top |
|
|
Ramona van Riet
Guest
|
| Posted: Sat May 06, 2006 1:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
Om 14:48:22 uur, 06.05.2006, schreef Bob Dawson:
| Quote: | "Charles Line" wrote
mostly nonsense I'm afraid. Speaking as a developer with several years
experience as a professional tech writer, this is exactly the ad I want
to see from Borland.
|
[Rest of excellent message removed]
That was an excellent explanation of what the advertisement actually
asked, instead of what Charles read into it. Thank you.
--
Ramona |
|
| Back to top |
|
|
John Jacobson
Guest
|
| Posted: Sat May 06, 2006 4:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
Charles Line
<charles (AT) ihatespamwithpsychoticintensity (DOT) clsinternal.notthisbittakeitout.net>
wrote in message <445c65ba (AT) newsgroups (DOT) borland.com>
| Quote: | "Research material without written technical specifications"
What does this mean? Are there swathes of material requiring documentation
that have no technical specifications?
|
I would say that it is probably the case that at least some of the products
that Borland acquired in acquisitions did not have technical specs, or no up to
date technical specs.
In addition, it is often the case that documentation needs to be started long
before any technical specs are finalized or written.
But I think the most important reason that you don't always want documentation
to be written from technical specs is that user documentation is an entirely
different type of beast than specs written for the developers of the software.
They serve two entirely different purposes.
--
***Free Your Mind***
Posted with JSNewsreader Preview 0.9.4.2369 |
|
| Back to top |
|
|
Charles Line
Guest
|
| Posted: Sat May 06, 2006 4:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Bob Dawson"
| Quote: |
mostly nonsense I'm afraid.
|
I hope you're right.
| Quote: | Speaking as a developer with several years
experience as a professional tech writer,
|
I bow to your experience.
| Quote: | this is exactly the ad I want to
see from Borland.
|
Will you be applying?
| Quote: |
"Research material without written technical specifications"
What does this mean? Are there swathes of material requiring
documentation
that have no technical specifications? Is is a free-for-all?
It means the same for a technical writer as it would mean for a
programmer:
that a very senior hire should be expected to be capable of greenfield
design and production, not just filling in and refactoring material that
others have already produced.
|
Do you take this to mean that this means "start from scratch"? It was the
bit about "without written technical specifications" that made me sit up and
go "huh?". In your experience what would you expect to be walking into?
[snip]
| Quote: |
"Produce clear, accurate, and well-organized documentation that requires
minimal editing with minimal direction"
Again, this is a tech writer IV position--a senior/leadership hire. Would
you prefer they hire someone who can't be trusted to produce production
quality work? Would you hire a senior/team-lead programmer who couldn't
produce production quality code without continual supervision and review?
|
Don't be silly. There is no writer on this planet that doesn't benefit from
the input and guidance of a good editor. Are you saying you trust an author
of any description to be objective enough to pass their own work to
publication? Methinks the world of Blogging has a lot to answer for in this
regard.
[snip]
| Quote: |
Actually this is exactly the caliber person that Borland /should/ be
hiring:
some one whou can come in to an agile team and be an impact player. And
the
fact that they're advertising the position while making layoffs elsewhere
may indicate an increased sense of the importance of documentation. It's
had
to see that as anything but good news.
|
OK, I'll admit that taking on 2 documentation staff whilst laying off
elsewhere does show promise, but I've been bitten so many times by
substandard and assumption-riddled documentation that it's become a bit of a
bete noir for me. |
|
| Back to top |
|
|
Charles Line
Guest
|
| Posted: Sat May 06, 2006 4:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Dave Nottage [TeamB]"
| Quote: |
It probably *is* just your imagination. How about asking, rather than
assuming the worst?
|
And who do you suggest I ask? |
|
| Back to top |
|
|
Bob Dawson
Guest
|
| Posted: Sat May 06, 2006 5:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Charles Line" wrote
| Quote: |
this is exactly the ad I want to
see from Borland.
Will you be applying?
|
Don't think so, no. They're asking for eight years experience and I only
have five. More to the point, however, I love being a software
architect/developer, and would find it very hard to go back. I much prefer
designing and writing the software than its documentation.
bobD |
|
| Back to top |
|
|
Bob Dawson
Guest
|
| Posted: Sat May 06, 2006 5:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"John Jacobson" wrote
| Quote: | to be written from technical specs is that user documentation is an
entirely
different type of beast than specs written for the developers of the
software.
They serve two entirely different purposes.
|
Good point. One of the things I liked about the ad was the distinction
between "conceptual, procedural, and API reference documentation"--something
that's been greatly lacking in software docs lately.
With the movement to on-line/on-screen documentation only, we're pretty much
left with mostly API docs (~object member help), with a real drought in the
areas of both big picture conceptual explanations, and middle-layer
how-and-why solution explanations. About the only place you get that for
anything these days is in third-party books.
On-screen documentation is great for context sensitive object/API
documentation. But when trying to grok the grand scheme of things, there's
nothing that beats a book or article.
It's very true that you used to be able to learn OOP from the manuals. No
one's really going to do that by pressing F1 nowadays.
bobD |
|
| Back to top |
|
|
Bob Dawson
Guest
|
| Posted: Sat May 06, 2006 6:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Fred Derf" wrote
| Quote: |
Ramona, did you already send your request to join the TeamB?
|
AFAIK, TeamB membership is my invitation only, there is no application
AFAIK, generally sound judgment and reasoning skills are merely required,
not sufficient conditions for entry.
AFAIK, no one has ever been invited based solely on non-tech postings. If a
person really wanted to be invited, this would not be the place to hang out.
| Quote: | right to cancel anything for any reason)
|
I know for a fact that TeamB actions in moderating these forums are subject
to internal discussion and review.
Did you have a specific point?
bobD |
|
| Back to top |
|
|
Joanna Carter [TeamB]
Guest
|
| Posted: Sat May 06, 2006 6:14 pm Post subject: Re: No wonder Borland Technical Documentation stinks |
|
|
"Fred Derf" <nospam (AT) nospam (DOT) com> a écrit dans le message de news:
445cdaee$1 (AT) newsgroups (DOT) borland.com...
| Ramona, did you already send your request to join the TeamB? (don't
| forget to request your free copy of Delphi 2006 Architect and your
| right to cancel anything for any reason
Fortunately, TeamB membership is by invitation only and is not based on
sycophantic adoration of Borland, but by *helping* people in the newsgroups,
rather than trying to stir up dissent, unjutified speculation and argument.
Ramona, I am not claiming you are being sycophantic BTW :-)
Joanna
--
Joanna Carter [TeamB]
Consultant Software Engineer |
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
FAQ
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
