The Importance of Good Hardware and Software Documentation

[fa icon='calendar'] Jul 11, 2016 3:37:03 PM / by Brittney Borowicz posted in audience, content, data sheet, design, Developer, document, documentation, engineer, General, hardware, hierarchy, Nathan Rockershousen, organization, outline, project, reader, software, style, task, technical writing, The Importance of Good Hardware and Software Docum, user manual, writer, writing

[fa icon="comment"] 0 Comments

By Nathan Rockershousen, Technical Writer

Technical documentation can be intimidating because it needs to include technically complex information in an “easy to digest” fashion. Having reliable documentation is crucial in helping users figure out how to use a product as well as aiding writers and developers in creating work of consistent and high quality. Whether the documentation is software or hardware oriented, it is essential that it focuses on a diverse variety of user experiences. This may seem like a daunting task, but there are a couple of things that writers can do to formulate a well-rounded and efficient document. Here are a few key steps in writing and creating quality documentation:

Understanding the Task: Before the writer even begins to construct their document, there are a couple of things they need to do. The first thing the writer needs to do is establish the type of document they are creating. There are a variety of different technical documents that can range from something like a user manual to a data sheet. It is important to coordinate with anyone else working on writing the document in order to establish the design, organization, and style. In addition to this, creating a time-table and an organized outline are ways of keeping the project moving and holding writers accountable for producing content.

Considering the Audience: Once the formatting and guidelines for the documentation are complete, it is important to understand who the audience is before beginning to transcribe any ideas. Being able to comprehend the background of the reader is critical because it establishes the way the content is written in terms of language, detail, and organization. It is important to know if the audience is technical or not in order for the writer to use appropriate references. Whether the writer is writing for a group of engineers within their company, or for an external group with no technical experience, the different audiences need different levels of detail. Regardless of who the audience is, it is critical to determine what information not to include, what information will confuse readers, and what information will make it difficult for a reader to digest the main points.

Writing the Document: When writing a technical document, one of the most important things to consider is the hierarchy of the information being used. Adding levels of hierarchy to categorize information can allow for a very coherent and granular organization system, but over-categorizing information can lead to confusion. Another simple thing that can be done to make important information easier to understand is writing paragraphs in a short and concise manner. The main point of a paragraph should be stated almost immediately so the reader knows if they are looking in the right place. Other beneficial things to do to make a document more user-friendly include reducing the amount of redundancy, providing tables and examples with explanations, avoiding jargon, and using clear sentences.

Even though the task of writing can be managed under the right instructions, proper documentation is often something that is neglected among developers and engineers. This is due to the fact that engineers are not natural technical writers. Writing documentation is tedious and requires a lot of attention to detail. Often these developers and engineers are the experts on the technical language and concepts, but being able to translate that knowledge into something that is coherent to someone who doesn’t understand the complexity of the technology can be difficult. The main issue with documentation is that it can go out of date very quickly. Having to constantly update software or hardware documentation can slow down engineers and developers in doing their actual jobs of creating new content. Even though there are negative connotations associated with engineers and their documentation ability, there are potential fixes to these issues. A potential solution can be training engineers how to communicate the simplicity found in complex ideas through technical writing training. In addition to this, having technical writers work with engineers to produce documents and update them can help ease the task of writing documents.

The time and cooperation it takes to write great documentation can be very beneficial for a business. Poorly written documentation will deter customers because the information they might need to use a product isn’t easily accessible. If engineers and developers cooperate to make proper documentation, there can be improved sales because the product information is much easier to reference. In addition to this, a well written document can provide adequate training on how to use a product, which will prevent customer errors. A well written document will attract customers and make it much easier to sell products.

Read More [fa icon="long-arrow-right"]

Employee Spotlight: Erik Krietsch, Senior Developer

[fa icon='calendar'] Sep 18, 2015 10:57:10 AM / by Brittney Borowicz posted in connectsense, ConnectSense App, Developer, Employee Spotlight, General, OpenHack

[fa icon="comment"] 0 Comments

i_guess_this_one_

Erik Krietsch is one of two developers we have here at Grid Connect. Erik spends a lot of his time working on the ConnectSense App. This involves adding new features and fixing bugs as well as a long list of all the things that go into putting out the best app possible.

Erik has always loved working with computers and started learning his first programming language when he was 15. After building up his skills in a variety of ways, he was able to start getting paid for what he loves to do when he was 20. After years of experience in a diverse array of jobs and mentorships, Erik met Adam Justice (VP of Grid Connect) and John Allured (Lead Developer at Grid Connect) at an OpenHack meetup. Soon after this, Erik joined the Grid Connect team and hasn’t looked back, “I find the work interesting” says Erik, “the problems we face are challenging without being monumentally frustrating.”

Erik enjoys running, reading comics, and playing with his two beautiful daughters (4 years and 10 months).

Read More [fa icon="long-arrow-right"]

Subscribe to Email Updates

Lists by Topic

see all