SYS-CON Media
 Register Now!
Save $200
Register before October 17th to SAVE! ... and also receive a FREE copy of the Best-Selling AJAX Book, a $119 Value!
Untitled Document
2008 East
Platinum Sponsor
Untitled Document
2008 East Gold Sponsors
Untitled Document
2008 East Exhibitors
Untitled Document
2008 East Media Sponsors
Untitled Document
2008 Association Sponsor
SYS-CON Media
2007 West Sponsors
Goingtomeet.com Conference Directory
SYS-CON Media
2007 East Sponsors
Untitled Document
2008 SYS-CON Events

Can't Miss RSS Feed
Subscribe to the AJAXWorld.com RSS Feed & Get All The Conference News As It Happens!

2008: Decision Year for RIAs - October 20-22, 2008 San Jose


Developing Quality Technical Information: Third Edition
A Handbook for Writers and Editors

As an enterprise and software architect the one thing I hate most about my job is documentation, yet the importance of doing documentation on sizable projects is what I find myself preaching about the most.

One reason I understand the importance of documentation is that I came from an electronic engineering background. As an electronic engineer 93% - 97% of my time was consumed doing proof of concepts and documentation. Almost all of that time was documentation.

It was just my luck that my boss was an English grammar teacher before moving into engineering. My documents came back very bloody. He used a red pen to mark up my documents. It took me 2 years, and a whole lot of tongue biting, but I started getting papers through him without a red mark. I still remember the first one. I walked outside to where the smokers took their breaks and let out a screaming "YES, Finally!!!"

I have been without my grammar teaching boss for over 18 years now, and I am pretty sure if he came across the book reviews I am writing now, he would be sending me bloodied up copies!!! I really needed this book!!

Technical documentation is a hard skill set to learn, at least doing good technical documentation is. I have been on Template Zombie projects where teams considered documentation complete when they had filled in enough templates to overwhelm the customer to the point where they would not have time to review 1/10 of what was being written.

One project I was on built a documentation generator so it was easier to duplicate documents and only change the title and a few pieces of content. The sad part of that project was they got paid for each document handed in. The criteria for getting paid for use cases were that they had to have something underneath every heading in the document.

Documentation should not be something you check off of the project's task list, it should add value to the project or it should not be done. This book will definitely help you make valuable documentation. I have listed the chapters below to give you an idea of what the book covers.

Part 1: Introduction
Chapter 1. Technical information continues to evolve
Chapter 2. Developing quality technical information

Part 2: Easy to use
Chapter 3. Task orientation
Chapter 4. Accuracy
Chapter 5. Completeness

Part 3: Easy to understand
Chapter 6. Clarity
Chapter 7. Concreteness
Chapter 8. Style

Part 4: Easy to find
Chapter 9. Organization
Chapter 10. Retrievability
Chapter 11. Visual effectiveness

Part 5: Putting it all together
Chapter 12. Applying more than one quality characteristic
Chapter 13. Reviewing, testing, and evaluating technical information

Part 6: Appendixes
Appendix A. Quality checklist
Appendix B. Who checks which characteristics?
Glossary
Resources and references

When I came into the Dot Com Boom I found some software engineering, but most of what I found was the wild west and cowboy coding running rampant. The industry has not changed much since then. We just gave names to the chaotic processes to justify our lack of discipline. I continued my engineering practices and quickly learned how to document software processes and architectures, but convincing others to do it was a different story.

The only way I have been able to show it has value is do it myself. After the team sees I am willing to suffer the boredom of documentation they tend to step in and help. That wouldn't happen if we didn't make use of the documentation and they didn't see value in it.

It has been years since I have had someone to officially review it. This book really helps keep the important things in mind, and since there is no one else to review it, I can use all the help I can get. Right now one of the things I do to catch issues in my documents is have them spoken back to me using the speech capabilities on my computers. This helps me catch sentence structure issues, and some typos. It doesn't catch using the wrong their/there, insure/ensure, except/accept, and many more like sounding words that I mess up.

I use Sparx Enterprise Architect to document systems. Behind every diagram you find the information that explains them. If that information is not simple to understand, and easy to read, the diagram's value falls greatly.

Throughout the process you need to write for several different audiences. Your stakeholders are interested in different aspects of the system. Creating a clear view of what each type of stakeholder wants to see is a painful process, but it always pays off.

It makes me think about the solution from angles I normally wouldn't. Not only think about them, but diagram and describe them in a way that the solution's diagrams and associated documents can stand on their own. It makes me justify and clarify all the decisions made about the system, before it is in production!

Doing documentation is like coding. You start with a shell of what you are building, and you add the details to the different topics with each iteration of your development cycle. Your goal- to make simple, complete, accurate, logical, easy to understand documents. That is exactly what this book will guide you to do.

There are tons of examples showing the original text, diagram, or screen shot of a design, and then the revised version. There are two really cool appendices and a nice glossary. The first appendix is a huge checklist for quality characteristic. The second appendix is a big chart showing which roles should be reviewing the different aspects of the document.

Over all I found every chapter of this book valuable. As time goes on, the hardest part for me is keeping it all in mind. For that reason, this book will be staying by my side just like each of my current most useful programming books. If you do any documenting of software systems, this is a must read. Every software architect, enterprise architect, CIO, developer, tester, and project manager working on a software project, should have this book in his or her hands. You own to your stakeholders and yourself.


Developing Quality Technical Information: A Handbook for Writers and Editors (3rd Edition)

Developing Quality Technical Information: A Handbook for Writers and Editors (3rd Edition)
About Tad Anderson
Tad Anderson has been doing Software Architecture for 18 years and Enterprise Architecture for the past few.

Latest AJAXWorld RIA Stories
"We're developing a software that is based on the cloud environment and we are providing those services to corporations and the general public," explained Seungmin Kim, CEO/CTO of SM Systems Inc., in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the ...
"MobiDev is a software development company and we do complex, custom software development for everybody from entrepreneurs to large enterprises," explained Alan Winters, U.S. Head of Business Development at MobiDev, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – N...
In his session at 21st Cloud Expo, James Henry, Co-CEO/CTO of Calgary Scientific Inc., introduced you to the challenges, solutions and benefits of training AI systems to solve visual problems with an emphasis on improving AIs with continuous training in the field. He explored app...
The question before companies today is not whether to become intelligent, it’s a question of how and how fast. The key is to adopt and deploy an intelligent application strategy while simultaneously preparing to scale that intelligence. In her session at 21st Cloud Expo, Sangeeta...
"We work around really protecting the confidentiality of information, and by doing so we've developed implementations of encryption through a patented process that is known as superencipherment," explained Richard Blech, CEO of Secure Channels Inc., in this SYS-CON.tv interview a...
Untitled Document

Call 201 802-3020 or Click Here to Save $200!

Register Today and
Save $200

Your registrations includes: Golden Pass Delegates will receive full conference access on October 20-22, 2008 including: Lunch and Coffee Breaks, Collectible Bag and Archives of all sessions on DVD. Includes access to all Conference Sessions including the Technical Sessions, Exhibits, Keynotes, Vendor Technology Presentations, and Power Panels.


Sponsorship Opportunities

AJAXWorld offers the undisputed best platform to position your company as a leading vendor in the fast-emerging marketplace for AJAX and Enterprise Web 2.0.


Please call
(201)802-3020


Who Should Attend?

 CTOs & VPs of Engineering
 Directors of Technology
 Sr. User Interface Architects
 Front-End Engineers
 VCs & Industry Analysts
 Directors of Business Development
 Software Engineers
 Senior Architects
 Application Programmers & Software Developers
 Project Managers
 Web Programmers & Designers
 Companies & Organizations that need to stay in
  front of the latest Web technology

AJAXWorld Security Bootcamp

Introducing at AJAXWorld RIA Conference 2008 West the world's first-ever full, one-day immersive "AJAX Security Bootcamp" - led by one of the world's foremost AJAX security experts and teachers, HP's Billy Hoffman.

View the full one-day schedule



AJAXWorld 2008 West - Tracks

Track 01: Enterprise RIAs
Track 02: Frameworks & Toolkits
Track 03: Web 2.0 & Mashups
Track 04: Hot Topics
Track 05: The Future of the Web
Track 06: iPhone Developer Summit



Brought To You By:

AJAXWorld Magazine is the pre-eminent independent vendor-neutral resource for the fastest growing new segment of the software business: entirely Web-based applications and experiences.

Download the Latest Issue!

AJAXWorld Webcasts



SYS-CON EVENTS


AJAXWorld Keynotes & Power Panels

2008 SYS-CON TV Keynotes: Can We Fix the Web? By Douglas Crockford - by Douglas Crockford
2008 SYS-CON TV Keynotes: 2008: The Year of the RIA - by Anthony Franco
2008 SYS-CON TV Power Panel: The Business Value of RIAs
2008 SYS-CON TV Power Panel: What Lies Beyond AJAX
2007 SYS-CON TV Keynotes: Why Web 2.0 for the Enterprise Is Far More Than Just a Facelift - by Ted Farrell
2007 SYS-CON TV Keynotes: Fueling the Next Generation Web: A Peek Behind the Green Curtain - by Bob Brewin
2007 SYS-CON TV Keynotes: AJAX in the Balance - by Joe Stagner

AJAXWorld Sessions on SYS-CON.TV

· Bill Scott - Yahoo! UI Library
· David Heinemeier Hansson - AJAX on Rails
· Jesse James Garrett - Elements of User Experience
· Dion Hinchcliffe - Real World AJAX
· Eric Miraglia - Open Source AJAX Development
· Paul Rademacher - Mashing Up Your Web Application
· Adam Sah - Google Gadgets
· Doug Crockford - An Introduction to JavaScript
· David Linthicum - Enterprise Web 2.0
· Patrick Grady - The Imagination & Experience Web

AJAXWorld...All The AJAX Rock Stars in One Spot!


Past Events Archive

SOAWorld Conference & Expo 2008 East
soa2008east.sys-con.com
Virtualization Conference & Expo 2008 East
virt2008east.sys-con.com
AJAXWorld 2008 Conference & Expo East
ajaxmar08.sys-con.com
SOAWorld Conference & Expo 2007 West
www.soaworld2007.com
Virtualization Conference & Expo 2007 West
virt2007west.sys-con.com
AJAXWorld 2007 Conference & Expo West
ajaxoct07.sys-con.com
SOAWorld Conference & Expo 2007 East
soa2007east.sys-con.com
Virtualization Conference & Expo 2007 East
virt2007east.sys-con.com
AJAXWorld 2007 Conference & Expo East
ajaxmarch07.sys-con.com
Other SYS-CON Events
events.sys-con.com

Join Over 10,000 Early AJAX Adopters
Who Have Attended AJAXWorld
• A&R Edelman
• Academic Enterprise
• Accoona Corp [2 delegates]
• Acxiom
• Adams Capital Management
• Adaptive Edge
• Adaptive Path
• Adobe Systems Incorporated [21 delegates]
• Adobe Systems Romania
• Ajax13
• All Risks, Ltd.
• alliance
• Alliance For Community Care
• AlphaDetail Inc
• Altera Corporation
• Amazon.com [6 delegates]
• Appeon Corporation [2 delegates]
• Apple Computer [5 delegates]
• Apress [3 delegates]
• Arkivio
• ASA
• Astute Solutions
• Avaya Inc [2 delegates]
• Avenda Systems
• Avenue A | Razorfish [3 delegates]
• Axcella, LLC [2 delegates]
• Aximsoft
• Azimyth
• Backbase USA Inc. [4 delegates]
• BAE Systems [2 delegates]
• Bank of America [2 delegates]
• Barkley Evergreen & Partners Interactive
• Bayview Financial [2 delegates]
• BEA Systems [3 delegates]
• Billeo
• BMC Software, Inc. [2 delegates]
• Borland Software Corporation
• Bradford Technologies, Inc [2 delegates]
• Brilliance
• Brocade Communications Systems, Inc. [2 delegates]
• Brookside Capital LLC
• Brulant
• Bungee Labs, Inc [6 delegates]
• Bureau of Labor Statistics
• BUZ Interactive
• Cadena Software
• Calix Networks
• Callidus Software [2 delegates]
• Cambia Security
• Carnegie Mellon West
• Cautella, Inc.
• CBSA
• Celequest [3 delegates]
• Change Vision, Inc.
• Charles E. Kenney, CPA
• Charles Schwab & Co., Inc. [8 delegates]

   read more...


ADVERTISE   |   MAGAZINE SUBSCRIPTIONS   |   FREE BREAKING-NEWSLETTERS!   |   SYS-CON.TV   |   BLOG-N-PLAY!   |   WEBCAST   |   EDUCATION   |   RESEARCH

.NET Developer's Journal - .NETDJ   |   ColdFusion Developer's Journal - CFDJ   |   Eclipse Developer's Journal - EDJ   |   Enterprise Open Source Magazine - EOS
Open Web Developer's Journal - OPEN WEB   |   iPhone Developer's Journal - iPHONE   |   Virtualization - Virtualization   |   Java Developer's Journal - JDJ   |   Linux.SYS-CON.com
PowerBuilder Developer's Journal - PBDJ   |   SEO / SEM Journal - SJ   |   SOAWorld Magazine - SOAWM   |   IT Solutions Guide - ITSG   |   Symbian Developer's Journal - SDJ
WebLogic Developer's Journal - WLDJ   |   WebSphere Journal - WJ   |   Wireless Business & Technology - WBT   |   XML-Journal - XMLJ   |   Internet Video - iTV
Flex Developer's Journal - Flex   |   AJAXWorld Magazine - AWM   |   Silverlight Developer's Journal - SLDJ   |   PHP.SYS-CON.com   |   Web 2.0 Journal - WEB2

SYS-CON MEDIA:   ABOUT US   |   CONTACT US   |   COMPANY NEWS   |   CAREERS   |   SITE MAP
SYS-CON EVENTS  |  AJAXWorld Conference & Expo  |  iPhone Developer Summit  |  OpenWeb Developer Summit  |  SOA World Conference & Expo  |  Virtualization Conference & Expo
INTERNATIONAL SITES:   India  |  U.K.  |  Canada  |  Germany  |  France  |  Australia  |  Italy  |  Spain  |  Netherlands  |  Brazil  |  Belgium
 Terms of Use & Our Privacy Statement     About Newsfeeds / Video Feeds
Copyright ©1994-2008 SYS-CON Publications, Inc. All Rights Reserved. All marks are trademarks of SYS-CON Media.
Reproduction in whole or in part in any form or medium without express written permission of SYS-CON Publications, Inc. is prohibited.