Do you have a new piece of software or hardware to roll out? It’s important to release documentation that will help users navigate the machine, platform, product, etc. Whether it’s a manual or set of procedures, it can be difficult to decide what information is essential to the user. For a new piece of hardware or software, you want to avoid overwhelming the user with lots of unnecessary documentation. The following questions can help you create a basis for your documentation.
What is the purpose of your documentation?
It's easy to get lost when you’re brainstorming how to start documenting something. Reminding yourself of the purpose of your documentation can be helpful in making sure you stay within the scope of your manual or procedures. This will help you navigate what is essential for the user to know and what information is unnecessary.
Who is the audience?
When creating documentation, it's essential to keep the audience in mind. Whether the audience is comprised of experts or beginners will drastically impact the content. Consider the examples below:
Option 1: If the audience is knowledgeable or competent with this kind of machine or software, you can assume they understand the basics and start with more advanced information.
Option 2: If the audience has little experience or training regarding this kind of machine or software, you can start with some basic information.
What safety information should the user know?
It is essential to include any important safety information the user will need to know prior to using the software or hardware. If machinery is included, there may be risks that the user needs to be made aware of to mitigate physical harm to themselves or the machine. If software is included, the user may need to mitigate risks associated to security breaches or data loss. Important safety information related to specific common and/or high-risk tasks should be included in those respective sections of your documentation. General safety information that applies to the software or hardware as a whole should be included at the beginning of the user manual or each procedure document. This will increase the likelihood that the user will read this information before proceeding to other parts of the documentation.
Safety information may include the following:
Personal Protective Equipment (PPE)
Mandatory Safety Courses
General Risks
Risk Mitigation and Safety Measures
How will the user interact with the software or hardware?
When working on a new hardware or software rollout, it can be difficult to remember what it was like when you didn’t know anything about the product. Our clients often find it helpful to have several people test the product from start to finish (whether it’s performing a task with a new piece of machinery or an online user portal). This will highlight any common questions that may arise and should be addressed in documentation. It can also create a foundation for the documentation. Once you have step-by-step instructions, it is important to go through each step before releasing the documentation to the user. Oftentimes, there will be slight hiccups in the process that will be caught during testing.
Who should the user contact with questions?
Ideally, any possible questions that the user may have should be addressed in the documentation to avoid an unnecessary back-and-forth. For example, you may consider collecting questions that arise for an FAQs and/or Troubleshooting section. Your documentation should be living – it should be consistently refined, updated, and added to as new questions or information arise. It is rare that you capture all essential information related to a new product in the first draft.
Although you may think all questions are addressed in your documentation, when releasing new software or hardware, it’s important that the user knows who they should contact with questions that come up. You may opt to add contact information to several sections for different tasks (e.g., contact [person #1] to reset your password, contact [person #2] to troubleshoot, etc.). This ensures the wrong person is not contacted and the user gets assistance in a timely manner.
How can Scriptorium help you?
Luckily, Scriptorium is experienced in creating documentation for new software or hardware. We can collect information from you in various ways, and then you can leave the drafting to us. Whether it’s interviews, recorded videos, copy and pasted information, or notes, we will work with what you provide us to create clear and concise user documentation.
Contact Scriptorium to see how we can help create documentation that suits your organization's needs.
댓글