It could be argued that every person who provides a service to another human being has been frustrated at least once by confusion. Confusion, frustration, and lost time all stem from communication that is imprecise, lacks clarity, or offers too little detail. In the web development world, we hope that every client understands exactly what they are getting from their consultants and that the development team is exactly on the same page with Product/Project management and the client’s vision. That is not always the case, but it certainly can be improved by adopting these simple habits in your technical communication.
Best practices for technical communication include URLs, screenshots, and descriptions of the desired outcome. In cases where users are seeing UI differences on different devices, application, operating system, and hardware information can be relevant too. The logged-in user account for a complex web application with role-based access controls may also be critical to root cause analysis. New Target has found that adoption of these best practices on web development projects has improved clarity, reduced inefficiencies, and facilitated velocity.
Try building up a habit of including the following three to five items in every ticket, bug alert, or requirements document you touch. When your technical communication is precise, detailed, and forward-looking, you will be paying yourself in time saved and peace of mind maintained.
When a URL is provided, we can immediately zero in on the right page. This is particularly helpful for rapid troubleshooting and for documents that reference multiple web pages.
The text of the button on the page that describes the services we provide to nonprofit clients needs an edit (newtarget.com/associations).
Visual aids are a great way to provide context and to indicate a specific part of a webpage. New Target recommends using the browser extension “Awesome Screenshot” for Google Chrome.
3. Desired Outcome
In a great partnership, clients will clearly communicate their vision to the consulting team. Describing the desired outcome (“Acceptance Criteria” in developer terms) informs New Target of the goal our solution needs to meet. Rather than just reporting that “X is wrong” or “Y is broken,” we recommend laying out what X or Y should be like once we’ve done our job.
The text of the button on the page that describes the services we provide to nonprofit clients needs an edit (newtarget.com/associations). It currently reads “Request A Quote” and this needs to be reworded to “Request More Info.” See attached screenshot.
4. Application, Operating System, and Hardware
Users access the web through a browser that runs in an operating system on a piece of hardware. Different applications (and application versions), OSs and devices have the capacity to produce differing web experiences. For example, a website may appear one way on Safari in iOS on an iPhone, a second way on an iPad, and a third way on Firefox in Windows on a Dell laptop. When issues are related to cross-browser variances, New Target always recommends that you note the application, operating system, and hardware you have running.
The font of the button looks funny to me. I am testing on Safari in iOS on an iPad, and the font looks different than it does on my PC/Windows/Firefox at the office. Please review at newtarget.com/associations and the attached screenshots of each version I am seeing. The font needs to be consistent across browsers and match our brand guidelines.
5. User Account
Complex web applications contain role-based access controls. This means that different types of users will be accorded varying sets of permissions and access. A staff user may be able to edit a field that a Volunteer user can only see. A user from one division may have no access to the data from another division. If you have logged into a web application with a set of credentials and are seeing an error, it is possible that this stems from the user role and permissions that you have been accorded. New Target recommends noting the access level of your logged in user account in instances like this.
I am logged in as [email protected], which holds a Volunteer user role. The dashboard (newtarget.com/dashboard) is loading for me but I cannot see any values, and my user role should have read access to all data, so I should be seeing values on the dashboard page. See the attached screenshot. Acceptance Criteria: Volunteer users will see all data on the dashboard page, though they cannot edit it.
New Target serves our clients best when technical communication is detailed, precise, and forward-looking. We recommend clients, PMs, and developers always provide URLs, screenshots, and descriptions of the desired outcome. Info about the application, operating system, hardware, and logged-in user account can be critical details in specific instances as well. We find that when we include the three to five items above by force of habit in all our communications. Let’s keep the process simple by providing a high level of detail up front!