|By Tad Anderson||
|August 12, 2014 11:00 AM EDT||
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?
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)
Puppet Labs is pleased to share the findings from our 2015 State of DevOps Survey. We have deepened our understanding of how DevOps enables IT performance and organizational performance, based on responses from more than 20,000 technical professionals we’ve surveyed over the past four years. The 2015 State of DevOps Report reveals high-performing IT organizations deploy 30x more frequently with 200x shorter lead times. They have 60x fewer failures and recover 168x faster
Sep. 3, 2015 05:15 PM EDT
SYS-CON Events announced today that G2G3 will exhibit at SYS-CON's @DevOpsSummit Silicon Valley, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Based on a collective appreciation for user experience, design, and technology, G2G3 is uniquely qualified and motivated to redefine how organizations and people engage in an increasingly digital world.
Sep. 3, 2015 05:00 PM EDT Reads: 545
Too often with compelling new technologies market participants become overly enamored with that attractiveness of the technology and neglect underlying business drivers. This tendency, what some call the “newest shiny object syndrome,” is understandable given that virtually all of us are heavily engaged in technology. But it is also mistaken. Without concrete business cases driving its deployment, IoT, like many other technologies before it, will fade into obscurity.
Sep. 3, 2015 04:30 PM EDT Reads: 431
All major researchers estimate there will be tens of billions devices - computers, smartphones, tablets, and sensors - connected to the Internet by 2020. This number will continue to grow at a rapid pace for the next several decades. With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo, November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Learn what is going on, contribute to the discussions, and e...
Sep. 3, 2015 04:15 PM EDT Reads: 103
Containers are not new, but renewed commitments to performance, flexibility, and agility have propelled them to the top of the agenda today. By working without the need for virtualization and its overhead, containers are seen as the perfect way to deploy apps and services across multiple clouds. Containers can handle anything from file types to operating systems and services, including microservices. What are microservices? Unlike what the name implies, microservices are not necessarily small,...
Sep. 3, 2015 04:00 PM EDT Reads: 141
The 3rd International WebRTC Summit, to be held Nov. 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA, announces that its Call for Papers is now open. Topics include all aspects of improving IT delivery by eliminating waste through automated business models leveraging cloud technologies. WebRTC Summit is co-located with 15th International Cloud Expo, 6th International Big Data Expo, 3rd International DevOps Summit and 2nd Internet of @ThingsExpo. WebRTC (Web-based Real-Time Com...
Sep. 3, 2015 03:00 PM EDT Reads: 1,604
As more and more data is generated from a variety of connected devices, the need to get insights from this data and predict future behavior and trends is increasingly essential for businesses. Real-time stream processing is needed in a variety of different industries such as Manufacturing, Oil and Gas, Automobile, Finance, Online Retail, Smart Grids, and Healthcare. Azure Stream Analytics is a fully managed distributed stream computation service that provides low latency, scalable processing of ...
Sep. 3, 2015 02:45 PM EDT Reads: 389
SYS-CON Events announced today that DataClear Inc. will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. The DataClear ‘BlackBox’ is the only solution that moves your PC, browsing and data out of the United States and away from prying (and spying) eyes. Its solution automatically builds you a clean, on-demand, virus free, new virtual cloud based PC outside of the United States, and wipes it clean...
Sep. 3, 2015 02:45 PM EDT Reads: 480
In 2014, the market witnessed a massive migration to the cloud as enterprises finally overcame their fears of the cloud’s viability, security, etc. Over the past 18 months, AWS, Google and Microsoft have waged an ongoing battle through a wave of price cuts and new features. For IT executives, sorting through all the noise to make the best cloud investment decisions has become daunting. Enterprises can and are moving away from a "one size fits all" cloud approach. The new competitive field has ...
Sep. 3, 2015 02:45 PM EDT Reads: 175
SYS-CON Events announced today that HPM Networks will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. For 20 years, HPM Networks has been integrating technology solutions that solve complex business challenges. HPM Networks has designed solutions for both SMB and enterprise customers throughout the San Francisco Bay Area.
Sep. 3, 2015 02:30 PM EDT Reads: 962
With the proliferation of connected devices underpinning new Internet of Things systems, Brandon Schulz, Director of Luxoft IoT – Retail, will be looking at the transformation of the retail customer experience in brick and mortar stores in his session at @ThingsExpo. Questions he will address include: Will beacons drop to the wayside like QR codes, or be a proximity-based profit driver? How will the customer experience change in stores of all types when everything can be instrumented and a...
Sep. 3, 2015 02:30 PM EDT Reads: 512
Introducing Containers & Microservices Bootcamp at @CloudExpo Silicon Valley | #Containers #Microservices
SYS-CON Events announced today the Containers & Microservices Bootcamp, being held November 3-4, 2015, in conjunction with 17th Cloud Expo, @ThingsExpo, and @DevOpsSummit at the Santa Clara Convention Center in Santa Clara, CA. This is your chance to get started with the latest technology in the industry. Combined with real-world scenarios and use cases, the Containers and Microservices Bootcamp, led by Janakiram MSV, a Microsoft Regional Director, will include presentations as well as hands-on...
Sep. 3, 2015 02:15 PM EDT Reads: 417
Moving an existing on-premise infrastructure into the cloud can be a complex and daunting proposition. It is critical to understand the benefits as well as the challenges associated with either a full or hybrid approach. In his session at 17th Cloud Expo, Richard Weiss, Principal Consultant at Pythian, will present a roadmap that can be leveraged by any organization to plan, analyze, evaluate and execute on a cloud migration solution. He will review the five major cloud transformation phases a...
Sep. 3, 2015 01:45 PM EDT
Amazon and Google have built software-defined data centers (SDDCs) that deliver massively scalable services with great efficiency. Yet, building SDDCs has proven to be a near impossibility for ‘normal’ companies without hyper-scale resources. In his session at 17th Cloud Expo, David Cauthron, founder and chief executive officer of Nimboxx, will discuss the evolution of virtualization (hardware, application, memory, storage) and how commodity / open source hyper converged infrastructure (HCI) so...
Sep. 3, 2015 01:15 PM EDT Reads: 142
SYS-CON Events announced today that Pythian, a global IT services company specializing in helping companies leverage disruptive technologies to optimize revenue-generating systems, has been named “Bronze Sponsor” of SYS-CON's 17th Cloud Expo, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Founded in 1997, Pythian is a global IT services company that helps companies compete by adopting disruptive technologies such as cloud, Big Data, advance...
Sep. 3, 2015 01:00 PM EDT Reads: 370
In today's digital world, change is the one constant. Disruptive innovations like cloud, mobility, social media, and the Internet of Things have reshaped the market and set new standards in customer expectations. To remain competitive, businesses must tap the potential of emerging technologies and markets through the rapid release of new products and services. However, the rigid and siloed structures of traditional IT platforms and processes are slowing them down – resulting in lengthy delivery ...
Sep. 3, 2015 12:45 PM EDT Reads: 639
In his session at @ThingsExpo, Lee Williams, a producer of the first smartphones and tablets, will talk about how he is now applying his experience in mobile technology to the design and development of the next generation of Environmental and Sustainability Services at ETwater. He will explain how M2M controllers work through wirelessly connected remote controls; and specifically delve into a retrofit option that reverse-engineers control codes of existing conventional controller systems so the...
Sep. 3, 2015 12:00 PM EDT Reads: 254
The web app is agile. The REST API is agile. The testing and planning are agile. But alas, data infrastructures certainly are not. Once an application matures, changing the shape or indexing scheme of data often forces at best a top down planning exercise and at worst includes schema changes that force downtime. The time has come for a new approach that fundamentally advances the agility of distributed data infrastructures. Come learn about a new solution to the problems faced by software organ...
Sep. 3, 2015 11:00 AM EDT Reads: 138
U.S. companies are desperately trying to recruit and hire skilled software engineers and developers, but there is simply not enough quality talent to go around. Tiempo Development is a nearshore software development company. Our headquarters are in AZ, but we are a pioneer and leader in outsourcing to Mexico, based on our three software development centers there. We have a proven process and we are experts at providing our customers with powerful solutions. We transform ideas into reality.
Sep. 3, 2015 10:45 AM EDT Reads: 575
Advances in technology and ubiquitous connectivity have made the utilization of a dispersed workforce more common. Whether that remote team is located across the street or country, management styles/ approaches will have to be adjusted to accommodate this new dynamic. In his session at 17th Cloud Expo, Sagi Brody, Chief Technology Officer at Webair Internet Development Inc., will focus on the challenges of managing remote teams, providing real-world examples that demonstrate what works and what...
Sep. 3, 2015 10:15 AM EDT Reads: 131