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.
Long, long ago, on Wed, 12 Jun 2002 17:18:20 +0100, in fact, "Jonathan West" <jwest -at- mvps -dot- org> wrote:
>... In some small shops, it is only as they write the code that they *discover* how they want it to work. The design follows the writing of the code, not the other way around.
Jonathan:
This does not only happen in small shops. I've been at places with 40 - 50 developers or more where no specification or overall design existed.
At many software companies, big and small, those who propose to write specs before code are branded sissies and don't last.
At other places, there is a design, but it resides only in the Chief Engineer's brain. So then what happens is that the various programmers set out to write code and then once it's done the CTO looks at it and if it's kind of like what he envisioned, it's ok and if not, the programmer has to re-write it. Course the CTO still doesn't have much time to explain what he had in mind, so it's a process of trial and error and the "design" never does get written down. (I'm using the pronoun "he" advisedly here. I've never worked for a woman Chief Engineer.)
I have been hired at some places, after software release and when they are in need of VC $ or approval by some governmental agency, to write the specs that authority figures want to see. In some ways, of course, it's easier to write specs AFTER the software is done, because you can read the code to determine what the "design" is.
Unfortunately, in many cases, it becomes very, very obvious that there never was a design. I always find many redundancies, inconsistencies and poorly-thought-out implementation and I OFTEN find HUGE bugs when I document these kinds of "designs".
When the design comes last, these issues are usually structural and by that time it's much too late to fix any of them except for the HUGE bugs. If the team wants to remedy them in subsequent releases, they will still need to continue to support the kludges they implemented before design. The overhead becomes enormous.
I once documented an XML-like middleware product. The syntax of the various tags seemed to me to vary randomly (i.e., sometimes verb first, sometimes noun first, some separated by commas, some by semi-colons, etc.). I spent HOURS trying to figure out what the pattern was -- why one tag went one way and the other another way. Finally, I asked and was told that different programmers had implemented different tags in different ways.
I asked how a user would be able to determine which syntax any particular tag used and was told that there was no logical way of determining this unless you knew which programmer had coded the particular tag; that's why the docs were vital to the success of the product.
I asked if it would be possible at some point to unify the syntax and was told that the parser had been altered so radically to accommodate the mess that it would require a total re-write of the parser. And, since users had already been using these tags for a while, we would still have to support all the tag formats for years afterward.
--Emily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ Emily Berk ~
~ On the web at www.armadillosoft.com *** Armadillo Associates, Inc. ~
~ Internet and non-internet application development, project ~
~ management, developer relations and extremely-technical technical ~
~ documentation that developers find useful. ~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
