Writing for developers vs non-developers

I work for a start-up software company.  We have a web-based business management service that I work on.  For a while, I was the only developer.  I had one other “team member”, but he was in Ohio and only helped me out when needed.  My boss is not a computer guy, he’s a businessman.  We don’t have a “tech support” team.  Me and my boss respond to the support emails from clients.  This has led to some interesting challenges in communication.

As the developer of the website, I know how things work internally.  I also can’t think the same was as the clients that use our software.  When my boss gives me a task, I sometimes need to be shown it so that i can make notes about it myself.  Without that, the written description might not make much sense to me.

The reverse is also true, when I enter a bug in our bug tracker or make an SVN commit, my boss doesn’t always understand what I’m trying to say, so I need to think of a way to “simplify” it.

For the most part, we understand each other, but there are times when further explanation is needed.  This also happens when reading customer support emails.  I don’t think the way they do, and I don’t always use the software the way they do.  So, when they claim something is broken, I don’t always understand what they were trying to do in the first place.  This is where I ask my boss to talk with them to clarify.  (P.S. “it doesn’t work” does not help us fix issues)

Anyway, in our office, it seems sometimes better to have demonstrations while people take notes, than trying to explain something in a way the other can understand.

– Eric aka ens3261


5 Tips for Writing a Software User Manual

I’ve had the opportunity to take part in many projects, some academic and some at work. In each place I learnt standards for working with these software user manuals, which weren’t the same; I had to adapt my own style to the one I was required to use. Many times I had to pick manuals to revise that were made by different people and some of them were really a disaster, with inconsistencies and poor redactions and explanations.

Here are five guidelines you could use the next time you need to work on a software user manual.


  1. Write an outline for the manual.

You should start by dividing the software manual into introduction, menus and submenus, toolbars and every other section or tool group the software would have. Remember that it should start by stating the purpose and requirements of the software, followed by the installation procedure. Also include some common tasks, advanced functions, and a F.A.Q. section.


  1. Create and maintain a style guide.

The software manual should have writing and design standards that would always need to be followed with no exceptions. If it is done like this, the maintenance and creation process of the manual would be easier; users would also find it easier to understand.


  1. Use active voice.

Even though you may have not thought about that, it is easier for the reader to understand if the manual directly gives him orders and instructions. In passive voice, the subject is unknown, which may confuse the reader.


  1. Use graphics.

It is easier to understand a manual with screenshots of the software rather than looking for each option or button while reading the manual. There is a saying “An image is worth more than a thousand words.” It reflects how important is the visual aid when you try to explain something new to someone. It can also simplify and reduce the text.


  1. Write clear instructions.

Even though it is obvious, some people forget that the user manual is a document for the user to understand the software, not for your supervisor who already knows everything related to the software. These instructions should use numbered lists and each number should just include a step.


Follow these 5 easy tips and you will notice a really big change on the feedback of your work.


Nestor Mancilla V.

Audience, the Struggle for the Highly Technical

Over the past decade or so I have been working in various highly technical environments as a network and systems engineer.  During this time I have often struggled with how to effectively communicate to a diverse audience where technical people are mixed in with the “less than technical”.


I am lucky enough to have a blend of personality and technical ability that some of those I have worked with seem to lack.  Because of this I am frequently assigned tasks that require me to communicate with senior management and other groups, both internal and external.  Often this requires that I find a way to communicate highly technical information to non-technical people.  At first, I had a tendency to assume that there was a baseline of knowledge in the audience that would allow me to speak to them as if I were speaking to a technical peer.  Obviously, this approach failed and I had to devise a new strategy that wouldn’t alienate those who were stronger in business and lacked technical understanding.  My next approach involved a lot of analogies and “dumbing things down” a bit.  This approach was failed and I not only made the technical members of the audience bored I also made the non-technical members feel like I was talking to them the way they talk to their children.


More recently I think I have found a way to live in the grey area between “baby talk” and “tech jargon” that seems to be more effective.  While I present technical information I try to pause and make statements like “is everyone on the same page” or “do we understand …” When possible I also try to make sure that everyone is visually engaged and not drifting off.  Presenting or publishing for a diverse audience is always be a struggle for me and something that I will always have to work hard to improve on.