Writing Forums

Writing Forums is a privately-owned, community managed writing environment. We provide an unlimited opportunity for writers and poets of all abilities, to share their work and communicate with other writers and creative artists. We offer an experience that is safe, welcoming and friendly, regardless of your level of participation, knowledge or skill. There are several opportunities for writers to exchange tips, engage in discussions about techniques, and grow in your craft. You can also participate in forum competitions that are exciting and helpful in building your skill level. There's so much more for you to explore!

Virtual Machines and Instructions: Tell me, Let me read about it, Show me

Lately at work I am creating several VMs for users to do their thing (using our software) with, as hosted machines simply can't meet their requirements.

In order for them to know what to do, which users are there, passwords, use cases, etc., I have a few documents for them to read, print out, reference as they get familiar with the VM.

Looking at the docs, I am struck by how different they are, due to my 'writing to my audience'. But it isn't as simple as that. My audience can be the same person, but the content is arranged differently based on what I am trying to show them. I am big on screenshots, being a visual person, and have found that for the 3 types of listeners/learners (tell me, let me read about it, show me), the 'show me' ones are the largest group, and also the most common denominator, or foundation.

What I mean by that is, even if you want to have something explained to you (common with much older people), pictures & animation re-enforce concepts well because the brain works that way. For those that want to read about something, the screenshots allow them to make sure they are doing what they should.

So back to 'writing to your audience', I write in a relatively small variety of ways:

- Educational
- Procedural
- Conceptual
- Communications

Educational is teaching. I need to start with concepts the reader is assumed to understand and build a bridge from that to where I need them to be. This is a very creative process, and there are no rules!

Procedural is a fancy way of saying instructions. Numbered steps. The hard part here is that you can't leave anything out, and you can't make any assumptions about the reader's knowledge that they bring to the task. The hard part of all this is to not write like you are talking to YOU (who already knows all this), but rather imagine yourself as a person who doesn't. It sounds easy, but it is hard not to say, "They should already know how to ...".

When in doubt, offer links & citations to places to know the per-requisites. The most annoying thing when reading is to have the author assume you know what you don't. We've ALL read bad instructions!

Conceptual is the act/art of introducing a new idea to someone in a compelling way. The purpose of the piece could be to get buy in, money, or just to warm them up to the idea. It might even be to reinforce a known concept, or see it in a different light/perspective. The reasons are endless!

The trick to successfully writing this style (hardly a genre) is once again not to make assumptions about your readership. When in doubt, go low. This means that if you can foresee a mixed audience, visualize the member with the least knowledge of what you are discussing in your piece, and use that as your foundation to build that bridge on.

Ideally, you should not 'lose' your least informed audience member. Sounds easy, but what do you do when your writing is passed around and read by those not anticipated?! As in the above, I suggest pointing readers to links & such so you don't appear to be talking down to them. You'll never be chastised for pointing to too much supportive/referential material. :)

Communications are those awful things like memos (does anyone do memos anymore?) and emails. I could lump in all the Marketing, Advertising, and public-facing work here, but to keep the discussion space narrow we'll talk about communicating with team members (what I call internal customers).

I hate these. Where I am never misunderstood in my writing, not a week goes by when someone doesn't [un]intentionally 'get confused'. It's another arm of the Office Politics Octopus, and it, along with doing expenses and other things not associated with creating deliverables, is the worst part of what I do. I dread it.

From making meetings to scheduling WebEx/Adobe meetings to emails, it is always a minefield. And yes, I do a lot of it. Some might consider [internal] emails to be professional/commercial writing, but I don't. Everything I've read about how to be better at internal communications has turned out to be crap people just made up. Either that, or what works for 99% of the world is useless to me.

Both are just as likely!


@kaminoshiyo what a nice comment! Thank you very much! I only wish this kind of worrying could be transferred to Fiction! Hahaha!

Blog entry information

Yumi Koizumi
Last update

More entries in Creative Writing 101