How to Write Technical Documents

Posted on June 18, 2015 by - Advice

How to write technical documents first depends on the kind of technical document you’re writing. This is the biggest factor in deciding tone, style, word usage, etc. Most of the technical documents I write are user guides (UG), or Best Known Methods (BKM). Both types of documents save your reader’s time and energy, and can make the difference when launching a product or training session.

How to Write User Guides/Manuals


User Guides or Manuals (UM), tend to be longer, more complicated, and have more references. They generally deal with product specs, building instructions, and the like. The longest UG I have worked on was over 4,000 pages, the shortest are less than ten. They all follow the same basic steps:

  • Introduction
  • Body of the Text
    • Tools Needed (if applicable)
    • Steps (usually with Images)
    • Final results
  • Conclusion
  • Appendix with resources (if applicable)

Then it is up to you, the writer, to take all that information that you have tested, or have been given, and make it into something that the end user is able to read.

How do you do that? You KISS* (Keep it Simple, Scribe**). Think about who your audience is, a skill that is always important when writing. When I write, I imagine that I am producing documents for my grandparents or my friends who are ESL speakers (English as a Second Language). English is a tricky language, and a technical document is complicated enough without translation issues. Avoid turns of phrase and spell out all acronyms the first time they are introduced. Don’t take for granted the things that you know, they may not apply in a different language.

Another neat thing about writing UG/UMs is the fact that you can get away with publishing a whole document without a single complete sentence. In fact, bullet points, numbered lists, and notes are your friends in technical documentation. Bring on the sentence fragments! Use tables and images to illustrate the instructions. This is a situation where a picture is really worth a thousand words, and visuals are easier to understand.

When it comes down to it, the document is a more detailed version of “put the thing in the other thing and turn it on,” or some variation of that idea. If you can get that message across to the users, you’ve done your job.

How to Write Best Known Methods/Internal Processes


I find that BKMs are easier to write. Usually, when you’re writing a BKM it is for an internal process that you work on regularly. Examples of BKMs are: instructions on posting a document to an internal portal, how to run a machine, or how to process software testing. Even if it isn’t something that you work on personally, you should work closely enough with the person giving you the instructions to complete the final project. If you feel like you don’t have enough information, talk with your manager/engineer to fill in the blanks.

BKMs work best with clear instructions, small words (unless they are process specific), and diagrams. Think about trying to put IKEA furniture together without the diagrams. My house would be filled with nightmarish semblances of furniture. These documents are often shorter than a UG, usually less than ten pages. The writing process is very similar:

  • Quick introduction, less than a paragraph.
  • Steps for the process, including sub-steps, diagrams, tools needed, and images.
  • Conclusion/Summary of the final product.

Right now you may be wondering what the difference is between a User Guide and a BKM, which is understandable as they are similar. Think of a User Guide as the full explanation and possibly a little history of the project, whereas a BKM is a quick “how to.” Essentially, the two documents cover the same basic ideas, but the detail they get into differs. Remember: always keep your audience in mind. User Guides often go to external users (a wider audience) and BKMs tend to be internal (a smaller audience).

Final Tips and Notes


Technical writing is much like any other style of writing; you are passing along information to your readers in the clearest way possible.

  • Bullets, notes, and number lists are your friends.
  • Add images whenever applicable, the entire document can be images with minor text notes if that’s what works.
  • Keep your audience’s technical knowledge in mind.
  • Spell out acronyms the first time they are used, and consider adding a table of acronyms if the document contains more than ten.
  • Use tables to keep track of test results.
  • Don’t get fancy with your language. The document needs to be readable, not pretty.
  • Commit to a positive relationship with your engineers/testers, this will make your job so much easier. Tech guys tend to like cookies, just an FYI.
  • Most of all have fun with it. Even technical writing can be enjoyable if you keep an open mind. Proof-positive: I love my job.

*Tech Writers LOVE acronyms, seriously we can have whole conversations in them.
**Traditionally, this ends with Stupid, but I think that’s rude and ablest.

Lessons From Starting a Co-Working Space

Posted on May 18, 2015 by - Advice

Three years ago, when I couldn’t stand working another day in my bedroom, I found desk space in my friend’s studio. At $100/month, it was an expense I couldn’t take lightly. I committed to this ‘experiment’ for three months.

Three years later, I’ve increased my income and productivity substantially, and gone from a sub-leaser in a three-desk studio to a co-leaser of a space that fits eight. With my two co-leasers, I’ve invested four figures in furniture, decoration, and a semi-private meeting room. Why did I go from sub-leaser to co-leaser? Here are my lessons learned from starting a co-working space.

Why level-up from desk-renter to desk-lord?


Our landlord invited us to. She offered to subsidize our rent for six months as we got ourselves together. We figured that was plenty of time to find other refugees from home offices and the café scene. Heck, maybe we’d even turn a small profit.

Building out the space, including our time, cost several thousand dollars. That semi-private meeting space took several more weekends than we were expecting. Fortunately, our illustrator friend Andy Lunday welcomed the opportunity to grace our walls with his art.

Should you start a co-working space?


Consider these questions first:

  1. Are you willing to set up a separate business entity?

    2. As soon as the three co-leasers decided to take the opportunity, we should have set up a separate LLC (Limited Liability Company). If nothing else, it would have kept our accounting clean. Though we collect our sub-leasers’ rent in a separate bank account, that ‘income’ will make 2015 taxes more complicated and costly.

    We were smart to define our agreement in writing. We specified what we were getting ourselves into, what we expected of one another, how we would make decisions, how we would deal with expenses and revenue, and what would happen if someone wanted to back out before the lease’s term came up. Even though it’s not a legal document, the exercise of writing it out helped us arrive at a common understanding.

    We also composed an agreement for our tenants. It’s not so much a legal document as a framework of our expectations and our offering. Since signing, no one has had to reference the agreement to settle disputes. Maybe that’s because we try to offer space to fair-minded people. Maybe we’ve just been lucky.

  2. Can you afford the time to market the space?

    3. When we first considered moving, we assumed that other freelancers would beat a path to our door.

    Hope springs eternal.

    We advertise on Craigslist, PivotDesk and with a sign in our front window. Though PivotDesk charges a 10% fee for the service, we’ve had more inquiries from Craigslist and the ‘desk space available’ sign.

    Since we consciously decided to undercharge other co-working spaces -believing that would do the attracting for us- there’s little incentive to make a substantial effort finding sub-leasers.

  3. What’s your ultimate goal?

    4. Unless you want to make this a viable business, or you have extra space in your office that you’d like to rent out on the side, you’re probably better off leaving this to someone else.

    If you just want to create, just create.

    If you hope to attract prospective collaborators (developers, designers, videographers, writers, etc.), put your effort into networking. Build up those relationships. With time, you may have enough prospective partners to share a lease and space where you can focus on creating.



That said, if you’re looking for affordable co-working space in Portland’s Central Eastside Industrial Neighborhood, please email us at studio3 [at] zoomtopia [dot] com.

We may be what you’ve been looking for.

How to Land Big-Name Clients

Posted on May 1, 2015 by - Advice

We all want to land big name clients. On average, they pay well, on-time, and having their names in our portfolio enables us to bring in even more clients like them. But how do we get them? If you’re going it alone, you’ll struggle longer to achieve this goal. If you combine your individual efforts with some strategic partnerships though, landing those big-name clients is kinda easy.

Here’s how to land big-name clients:

  • Creative Staffing Agencies
    1. Staffing agencies for creatives (copywriters, graphic designers, photographers, producers, etc.) have relationships with the largest companies in any city. They know all the Big Names and they can get you a gig or a job with them. I’ve added some awesome work and Big Names to my portfolio thanks to some of the creative staffing agencies (CSA) in Portland.

I highly recommend you locate some, or all, of the CSAs in your city and tell them what kind of work you want to do and for whom you want to do it. Many have multiple locations around the U.S. and the world. Here are a few: Mathys+Potestio, Filter Digital, 24Seven, 52 Ltd., and Aquent.

    1. Design/Advertising Agencies

Most marketing/digital/design/branding/advertising agencies survive because they have at least one Big Name client. It could be Target, Intel, Nike, Nordstrom, or The Standard. These agencies work with the biggest of the big, the creme de la creme, and they need all kinds of different creative abilities and content. Work can range from internal process documentation to B2B partner/vendor communications to B2C product descriptions and social content. Design agencies are often a one-stop advertising shop.

If you’re one of the creatives they call on for work, there’s a pretty good chance you’ll be working on some Big Name accounts. Not all creatives want to work with agencies though. That’s fine. If you don’t like having to deal with the middle-men, focus on some direct routes.

    1. Ask Your Network for Referrals

Let’s say you’ve got your eye on a Big Name client, but you don’t know anyone who works there. Do you know anyone who knows someone who works there? Probably. Ask your friends and family if they can refer you to someone in the target department at Big Name X. If you’re good at what you do, there’s no reason why they wouldn’t. You can also ask people in your LinkedIn network to recommend you to their connections with whom you’d like to connect.

Invite people to help you! More often than not, they’ll be happy to.

    1. Cold-Call

Don’t know anybody, or anybody who knows anybody, at Big Name X? Cold-call the hiring person in the department you’re targeting (Marketing, HR, Product Design, etc.) and introduce yourself. I’ve sung the praises of cold-calling many times on this blog and I will continue to do so! You’re not a telemarketer, and you’re not calling apartment-dwellers asking them if they’d like to buy aluminum siding. You’re a skilled service/product provider calling to offer something that the person needs, and would probably make their life easier. Don’t forget that.

Oh, and you can cold-email people on LinkedIn if you have a Premium account. They call it InMail. Not everyone accepts InMail, but this is another “cold-call” route if you’re terrified of using the phone (and a lot of people are, so you’re not alone).

    1. Go Where They Go/Network

The best way to make lasting connections is still the oldest way: face-to-face. If you can find a conference, networking event, or any other event where a representative of Big Name X will be, go there. Find them, meet them, and be your usual charming self. Design agencies AND creative staffing agencies host events where they invite reps from Big Name companies. Get on their mailing lists and check their Events pages regularly.

Check out the links, see if you’re interested in connecting with these agencies. If so, come to the event ready to introduce yourself to them. And be sure to introduce yourself to me as well, because I’ll be there and I’d love to meet you.

What other ways do you recommend landing big-name clients? How did one of these five methods land you a big-name client? I’d love to know.

3 Ways to Up-Level Your Business

Posted on April 18, 2015 by - Advice

How you up-level your business depends on your definition of success. For the sake of this post, let’s assume we’re talking about the kind of success that’s measured in dollars, i.e. making more of them rather than less. Here are three ways you can take your business from small fish to big fish.

  1. Collaborate with Partners


    2. Whether they’re going the same place you are, or you’re passing through the same orbit for a short period of time, find business partners who can help you take your business to the next level. Copywriter Peter Bowerman is a big advocate for copywriters partnering-up with graphic designers. He even wrote an e-book on the subject called Profitable By Design: Tapping the Writer/Designer Partnership Goldmine. In it he describes how great it is for a client when a graphic designer goes into a meeting and says, “Yes, I can design this for you. Have you thought about the writing? If you like, I can contact my copywriter partner and take care of all of this for you.” Clients love a one-stop shop solution.

    Another example comes from an artist/photographer friend of mine who’s actively moving his “small fish” business into a “big fish” business. He’s found a niche providing a rotating artwork and photography service for medical offices and hospitals. He wants to expand in that arena, but he’s not sure how. One idea (that I just thought of and haven’t shared with him yet!) is to locate interior design firms that specialize in decorating medical offices and hospitals. He could become one of their vendors, and get them to sell him! Just like the example above where the designer sells the writer. (I’ll call him later to tell him.)

  2. Go Where the Money Is


    3. It’s possible that the reason you’re struggling to take your business to the next level is because you’re just not going where the money is. I’ll use myself as an example. I’m a B2B and marketing copywriter. In previous years, I networked in the small business/solopreneur circuit. I made some great connections, did a few small projects, but nothing big. Nothing that would lend itself to taking me from small fish to big fish (or at least a bigger fish). The amount of time I spent building relationships with this particular group did not translate into my preferred amount of income.

    The lesson I learned? This was not my ideal target audience. So I had to re-think my marketing strategy to align with my business goals. I pivoted my focus from marketing copy for small businesses, to B2B and marketing copy for agencies and larger businesses (preferably with a technical or corporate messaging slant). Since embarking on this focus, I’ve landed some absolutely incredible projects with my ideal clients, doing my ideal kind of writing.

    Figure out where the money is within your particular expertise, and pivot your business (ideally without compromising your happiness) to gain a slice of that pie.

  3. Create a Source of Passive Income


    4. What could be better than making money while you sleep?! Or while you’re on vacation (a real vacation, no work allowed)? It’s all about the passive income. There are only so many hours in the day, and only so many of them you can spend working (especially if you have a partner, pets, children, hobbies, etc). You could create a situation like I mentioned above where someone else is selling your work for you, or you can create a product (e-book, online video training course, website/blog on which you can sell ad space, etc.) that doesn’t require your daily attention.

    With a passive income source, you’ll be able to do the work that takes up hours of your time (and yes, the initial creation of the passive income product will take your time), AT THE SAME TIME your passive income source is making money too.

Those are the three ways I’m planning to up-level my business in the near- and far-term. Obviously they won’t happen overnight, but taking small steps towards one at a time (or simultaneously if that makes sense for your business and sanity) today, is going to make a huge impact on my business/income in the future. My list is by no means exhaustive, but hopefully the items mentioned are within accessible reach for us all.

How are you up-leveling your business? Give us some more ideas!

Are You a Copywriter or a Content Strategist?

Posted on April 9, 2015 by - Advice

are you a copywriter or a content strategist?

A few weeks ago, a financial advisor friend of mine and I had a conversation about the terminology of our respective professions.  I mentioned how a few people seemed ambivalent about calling themselves copywriters, and some had started using the term, “content strategist.”

I get it.  “Copy” is a journalism term and one that evokes smoky newsrooms and clattering typewriters. And when you talk about “copywriting,” people think you’re talking about patents and intellectual property, e.g. copyrights.  (I help educate my editing clients about copyrights, but that’s a different subject.)  My friend mentioned there was a similar distinction being made between “socially responsible investing” and “impact investing.”

Earlier this month, the Copywriter Conclave of Portland held a lively discussion about what we call ourselves (and a necessary discussion since “copywriter” is such an important part of the Conclave’s branding).  There was speculation that content strategists are different because some are responsible for managing data sets and keeping track of a company’s content libraries.  Some content strategists are also responsible for creating directions for a brand or a product line.  We all agreed that content strategist sounded sexier than copywriter.

I include the title content strategist on my marketing materials (including my website), but I list my role as writer first.  I believe writing is a strategic activity.  Many may feel writers are passive creators.  Writers implement, but strategy is created by someone else.

That’s not me.  It’s true that when I started writing professionally in Portland, I took direction from my bosses.  But within two months, my overwhelmed direct boss was unable to give me much content direction.  So I started running comps and creating product descriptions based on what the customer would like.  I didn’t always get it right, but I was also the in-house editor, so I was able to adjust during the revision process.  It made me a more proactive writer, and I tried to encourage strategic writing when I moved into a managerial role.  The key here is that the strategy and writing were interwoven in my approach.

Today, as the owner of my own content-focused business, I’ve extended that process even further, starting with the proposal phase:

  • Determine the initial “power content” (book, e-book, website, and so on)
  • Create a consultation strategy based on client comfort (phone/e-mail/in-person/Skype)
  • Build a deadline schedule
  • Offer regular content (preferably evergreen) that solidifies their reputation or allows them to reach a goal (through blog posts and whitepapers)

Information-rich content is being touted as search-engine friendly now, but it was a survival strategy for me in the beginning of my business. I want my clients to know I’m invested in their prosperity. When prospects hire me, they get the benefit of my entire experience … strategy, editing, consulting, the whole thing.

But I am a writer first.

—

If you own a business, what sounds better to you … a writer or content strategist?   If you’re a fellow content creator, what do you call yourself?

(This post originally appeared at Enlighten Writing.)