How to Write ‘Scannable’ Web Content

Need to improve your web content? How much words should I put on a web page? How do I present the material? How do I know that anyone reads it? Research suggests that users don’t read on the web –  they scan. This means that when you are converting documents to the web, you need to […]

How to write documents for SaaS web applications

SaaS and web-based applications are becoming more popular as they replace desktop or network installations. How you document them is mostly the same as documenting traditional but there are some difference. Let’s take a look. Registration – explain how to set up the account, register an account, common setup issues, and troubleshooting, for example, if […]

How to write Enhancements for Release Notes

What do you need to include in your enhancement release notes? At a minimum, you need to cover the following: Description – identify the new enhancement. Avoid the words new, enhancement, or feature in the title. You can drop these words as it’s implied that it’s an enhancement as it’s in the Enhancement section of […]

Release Notes – How to Write ‘Known Issues’

This week we look at how to document known issues in release notes. The Release Notes web page on the NuGet site offers good examples of how to document known issues in release notes. We’re going to look at three common issues: Installation issues Known issues Workarounds Let’s see what we can learn from it. […]

Release Notes: 13 Mistakes to Avoid

It’s easy to overlook the importance of release notes. But when customers want to know exactly what a specific parameter does, it’s the release notes that often turn too. Why? Remember, for very large document sets, it can hard to know which document contains the reference material you need to understand. For this reason, configuration […]

How to make detailed Business Process Flowcharts easier to read

Isn’t the advantage of creating process flowcharts to help the reader see how it works instead of having to read the MS Word document? But what happens if the process is so complex that the diagram becomes almost unreadable? Instead of helping business analysts understand the process, it adds another layer of complexity. In addition, […]

How to Write Your First Test Case

One of the difficulties in writing your first test case is that it’s hard to know where to start. Writing test cases is not that difficult if you understand who you’re writing for and what you’re hoping to achieve. What’s the purpose of a test case? The purpose of a test case is to: Describe […]

The 10 Commandments of Software Maintenance Plans

What’s the best way to write a Software Maintenance plan? Software Maintenance Plans are different than other technical documents in that the focus is on how to modify software AFTER it has been released and is now in operations. Most other documents focus on planning, development or testing. Download Now How to Write Software Maintenance […]

How do you know whether you’re writing well?

How do you know whether you are writing well? There’s only one test that really matters: when your audience understands your information and is moved to act in accordance with your goals. But how will you know when this happens? The odds are pretty good that, early in your career anyway, you won’t have any […]

Difference Between Operations Manuals & Procedures Guides

What’s the difference between an Operations Manual and a Procedures Guide? At first glance, it’s easy to see the confusion as both contain procedures that need to be followed. However, if we look at them a little more closely, we can where and how they differ. Operations Manuals v Procedures Guides Samantha emailed me to […]