Welcome!

AJAX & REA Authors: Elizabeth White, Trevor Parsons, ChandraShekar Dattatreya, Liz McMillan, David H Deans

Related Topics: Virtualization, SOA & WOA, .NET, AJAX & REA

Virtualization: Book Review

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)

More Stories By Tad Anderson

Tad Anderson has been doing Software Architecture for 18 years and Enterprise Architecture for the past few.

@CloudExpo Stories
“DevOps is really about the business. The business is under pressure today, competitively in the marketplace to respond to the expectations of the customer. The business is driving IT and the problem is that IT isn't responding fast enough," explained Mark Levy, Senior Product Marketing Manager at Serena Software, in this SYS-CON.tv interview at DevOps Summit, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
Mobile commerce traffic is surpassing desktop, yet less than 20% of sales in the U.S. are mobile commerce sales. In his session at 15th Cloud Expo, Dan Franklin, Segment Manager, Commerce, at Verizon Digital Media Services, defined mobile devices and discussed how next generation means simplification. It means taking your digital content and turning it into instantly gratifying experiences.
The Internet of Things is a misnomer. That implies that everything is on the Internet, and that simply should not be - especially for things that are blurring the line between medical devices that stimulate like a pacemaker and quantified self-sensors like a pedometer or pulse tracker. The mesh of things that we manage must be segmented into zones of trust for sensing data, transmitting data, receiving command and control administrative changes, and peer-to-peer mesh messaging. In his session a...
"Ulunsoft is a start-up that focuses on how enterprises build cloud-based IT infrastructure for business," explained Haibo Zhu, President of Ulunsoft Corp, in this SYS-CON.tv interview at Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
"At our booth we are showing how to provide trust in the Internet of Things. Trust is where everything starts to become secure and trustworthy. Now with the scaling of the Internet of Things it becomes an interesting question – I've heard numbers from 200 billion devices next year up to a trillion in the next 10 to 15 years," explained Johannes Lintzen, Vice President of Sales at Utimaco, in this SYS-CON.tv interview at @ThingsExpo, held Nov 4–6, 2014, at the Santa Clara Convention Center in San...
As enterprises engage with Big Data technologies to develop applications needed to meet operational demands, new computation fabrics are continually being introduced. To leverage these new innovations, organizations are sacrificing market opportunities to gain expertise in learning new systems. In his session at Big Data Expo, Supreet Oberoi, Vice President of Field Engineering at Concurrent, Inc., discussed how to leverage existing infrastructure and investments and future-proof them against e...
“The year of the cloud – we have no idea when it's really happening but we think it's happening now. For those technology providers like Zentera that are helping enterprises move to the cloud - it's been fun to watch," noted Mike Loftus, VP Product Management and Marketing at Zentera Systems, in this SYS-CON.tv interview at Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
"For over 25 years we have been working with a lot of enterprise customers and we have seen how companies create applications. And now that we have moved to cloud computing, mobile, social and the Internet of Things, we see that the market needs a new way of creating applications," stated Jesse Shiah, CEO, President and Co-Founder of AgilePoint Inc., in this SYS-CON.tv interview at 15th Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
"Desktop as a Service is emerging as a very big trend. One of the big influencers of this – for Esri – is that we have a large user base that uses virtualization and they are looking at Desktop as a Service right now," explained John Meza, Product Engineer at Esri, in this SYS-CON.tv interview at Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
SYS-CON Events announced today that Gridstore™, the leader in hyper-converged infrastructure purpose-built to optimize Microsoft workloads, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Gridstore™ is the leader in hyper-converged infrastructure purpose-built for Microsoft workloads and designed to accelerate applications in virtualized environments. Gridstore’s hyper-converged infrastructure is the ...
"People are a lot more knowledgeable about APIs now. There are two types of people who work with APIs - IT people who want to use APIs for something internal and the product managers who want to do something outside APIs for people to connect to them," explained Roberto Medrano, Executive Vice President at SOA Software, in this SYS-CON.tv interview at Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
"Application monitoring and intelligence can smooth the path in a DevOps environment. In a DevOps environment you see constant change. If you are trying to monitor things in a constantly changing environment, you're going to spend a lot of your job fixing your monitoring," explained Todd Rader, Solutions Architect at AppDynamics, in this SYS-CON.tv interview at DevOps Summit, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
Today’s enterprise is being driven by disruptive competitive and human capital requirements to provide enterprise application access through not only desktops, but also mobile devices. To retrofit existing programs across all these devices using traditional programming methods is very costly and time consuming – often prohibitively so. In his session at @ThingsExpo, Jesse Shiah, CEO, President, and Co-Founder of AgilePoint Inc., discussed how you can create applications that run on all mobile ...
"SOASTA built the concept of cloud testing in 2008. It's grown from rather meager beginnings to where now we are provisioning hundreds of thousands of servers on a daily basis on behalf of customers around the world to test their applications," explained Tom Lounibos, CEO of SOASTA, in this SYS-CON.tv interview at DevOps Summit, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
“We are a managed services company. We have taken the key aspects of the cloud and the purposed data center and merged the two together and launched the Purposed Cloud about 18–24 months ago," explained Chetan Patwardhan, CEO of Stratogent, in this SYS-CON.tv interview at 15th Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
We certainly live in interesting technological times. And no more interesting than the current competing IoT standards for connectivity. Various standards bodies, approaches, and ecosystems are vying for mindshare and positioning for a competitive edge. It is clear that when the dust settles, we will have new protocols, evolved protocols, that will change the way we interact with devices and infrastructure. We will also have evolved web protocols, like HTTP/2, that will be changing the very core...
"Verizon Digital Media Services is responsible for the broadcast, video and content delivery network that accelerates, scales and helps our customers reach end users with all kinds of video and web content," stated James Segil, CMO of Verizon Digital Media Services, in this SYS-CON.tv interview at 15th Cloud Expo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
SYS-CON Events announced today that Creative Business Solutions will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. Creative Business Solutions is the top stocking authorized HP Renew Distributor in the U.S. Based out of Long Island, NY, Creative Business Solutions offers a one-stop shop for a diverse range of products including Proliant, Blade and Industry Standard Servers, Networking, Server Options and...
You use an agile process; your goal is to make your organization more agile. But what about your data infrastructure? The truth is, today's databases are anything but agile - they are effectively static repositories that are cumbersome to work with, difficult to change, and cannot keep pace with application demands. Performance suffers as a result, and it takes far longer than it should to deliver new features and capabilities needed to make your organization competitive. As your application an...
“We are strong believers in the DevOps movement and our staff has been doing DevOps for large enterprise environments for a number of years. The solution that we build is intended to allow DevOps teams to do security at the speed of DevOps," explained Justin Lundy, Founder & CTO of Evident.io, in this SYS-CON.tv interview at DevOps Summit, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.