Category: Writing

Investing in good equipment

Business Coding Lifestyle Personal Writing

Investing in good equipment

A younger, more innocent me bought a 13″ mid-2014 MacBook Pro on closeout in early 2015. My main tasks for my computer at that time were writing documents in word processors (Pages) and using CMSs to create and publish content. I thought I might do some light video editing of travel videos for Corporate Runaways, but didn’t have much need or desire for a powerhouse machine. I had an external monitor for additional screen real estate, and mostly used the laptop screen for reference material.

Fast forward to 2019. In the past few years, I’ve started doing docs-as-code in conjunction with a few open source projects. From the open source project side, this has involved setting up local development environments on my machine, and running apps locally so I can document them. From the documentation side, this has involved using static site generators to create doc sites from files (markdown, mostly). My work needs have definitely gotten more intensive.

Then, this spring, I dove into Swift. When I decided to learn to code so I could write an app I want to use, I took a gradual approach. I worked through some Swift Playgrounds stuff on my iPad, and then read a book or two about coding and Swift. I brainstormed the data structure for my app, and made UML diagrams. Eventually, I took a couple of online classes on Xcode and Swift.

Between my technical writing work and my app development, my 13″ laptop + external monitor had begun to feel cramped. What had once felt sufficient for doing marketing writing in a single window, with maybe a reference window alongside, had now become a nightmare of overlapping windows and constant swapping. I wanted more screen real estate so I could have multiple windows open for reference and working simultaneously, and I wanted those windows to be bigger.

But mostly, I wanted Xcode to not just laugh at me when I attempted to compile things, or – even worse – not have Xcode sputter when I attempt to Auto Run a Playground so I can see how things are working as I code.

One of the classes I took involved working in Playground files on my machine as I followed the instructor’s videos. I had to keep pausing the instruction video to wait for my local Playground to respond to my inputs, while the instructor did the exact same thing in the video and then happily chugged along with his much more powerful machine.

It was clear. Xcode was a memory/processor hog, and I had too little of both. I’d been bumping up against those limits for a while now with my other work, but the app development pushed me over the edge. So it was time… time to upgrade my equipment.

(Don’t get me wrong – that little 13″ mid-2014 MBP did well to get me into mid-2019 without a hitch, and is still chugging along happily with less intensive tasks; it’s my “couch computer” now.)

I looked around at the options. I could get a newer, more powerful MacBook Pro. But I’d still have limited screen real estate, and that was chafing more and more. Also, I essentially never use my laptop as a laptop these days; I work exclusively at my desk, with my Kinesis Advantage2 keyboard and my external monitor setup. Could it be time to go back to a desktop, when I still remembered fondly the liberating joy of going from a PC tower to my first laptop back in the mid-2000s? It seemed like such a step back, it was hard to fathom.

But the more I thought about it, the more it seemed to make sense to get a desktop again. I never use the laptop as a laptop. I could get better CPU/more RAM significantly cheaper with a desktop. And then I could have another big monitor, giving me the screen real estate I’ve been craving.

I decided to go back to a desktop. I clearly didn’t need a powerhouse like the newly-announced Mac Pro, so I wasn’t going that route. I looked at the Mac mini; a capable little machine. I looked at the iMac, with its beautiful monitor. I looked at the iMac Pro – nope, that’s more than I need.

Waffle. Research external monitors. Waffle. Spec out both machines to a level that would support my current needs, plus some future-proofing. Cringe at the price tag. Waffle some more. Deal with some stupid imposter BS because my husband is the experienced web dev, and how could I justify spending that much on a setup for my less-intensive work + dabbling in Swift development; an entirely self-driven project that may never make me a penny?

Eventually, I drove the hour to the nearest Apple store to see an iMac in person. And then I sat myself down and gave myself a pep talk about giving myself permission to invest in my skill development. Maybe I’ll get more heavily into coding as a tech writer. Maybe I’ll love developing in Swift so much that I’ll pivot to Mac app development. Or maybe I’ll write this app, but then decide that coding isn’t something I want to pursue beyond that. I won’t know unless I give myself the room to develop those skills and see what happens, but it is 100% OK to invest in my career potential.

So I pulled the trigger, and got a beautiful 27″ iMac. And it isn’t the entry-level iMac, either; it’s closer to the top tier, to give myself room for growth.

And you know what? It is frigging delightful. It’s so fast. And the screen is so beautiful. It’s a little painful to use it right next to my old external monitor, which isn’t even 4k; the resolution drop and seeing visible pixels is a little jarring looking back and forth. I expect I’ll upgrade that, too, soon. But my tech writing work has been much more hassle-free with the extra screen real estate, and staring at text on a retina-resolution screen is delightfully enjoyable.

So here’s a reminder, if you need one, too: investing in good equipment is an important part of taking your professional life seriously. This is mission critical for remote workers who don’t have office-supplied equipment. I see a lot of remote workers sitting on their couch and typing on a laptop keyboard; that’s a good way to ruin your hands, your back, your posture, and reduce your efficiency and output. (Trust me, that’s how I started out with my remote work back in 2007.)

Yes, I am extremely privileged to be able to spend the money on an Apple device; I know you pay a big premium for their products. And I know that not everyone has the financial freedom to invest in big, splashy monitors and professional-quality office equipment; especially for folks who are the sole breadwinners, or supporting family members. But it is worthwhile to put money aside and invest in the equipment you need for your career, in whatever form you’re able and whatever that equipment looks like for you.

I am very much enjoying my new setup.

Choosing the best writing tool

Business Writing

Choosing the best writing tool

In my recent technical writing job search and interviewing process, I’ve encountered a lot of discussion around tooling. I always ask about the toolchain for a position I’m considering, and I’m happy to talk tools all day long. But the truth is, I’m tool agnostic. My questions about toolchain aren’t about deciding if you use a tool I like; they’re about discovering the maturity of your process.

That’s because there is no such thing as a one-size-fits-all writing tool.

I had an interviewer ask me recently: “When you sit down at the computer to write, what app do you open?” He seemed a little surprised when I responded: “That depends entirely on what I’m writing.” Here’s why:

Different writing tools are designed for different tasks. There are also a lot of ancillary tools related to writing tasks that a writer might need to use in the course of the job.

Word processors

When the general public thinks about writing on a computer, they typically picture a word processor, such as Microsoft Office or Apple’s Pages. I’m also seeing more and more enterprises using Google Docs for basic word-processing tasks, as part of G Suite adoption within the orgs.

Currently, I don’t use word processors very often. I’d typically fire this type of app up when working on a simple article or marketing piece. The majority of the time these days, I’m only using a word processor when editing something a client has sent me. It’s fine for simple revision work, or working with simple content, but if you’re hiring a technical writer and you want complex deliverables in Microsoft Word, I might run the other direction.

(Not because I don’t know how to use the more advanced functionality of these tools, like Table of Contents, etc. – but because this isn’t the best tool for long-form or sophisticated content needs, and if it’s the tool you rely on, that tells me a lot about your organization’s documentation processes. But that’s a whole ‘nother blog post…)

Long-form writing

One of my favorite writing apps ever is Scrivener. I’ve spent a fair amount of my time over the years drafting long-form content; think novels and business books.

I think it is the single best writing tool for long-form content out there; it has amazing support for organizing and re-ordering content, revision workflow, storing relevant research and notes within the app, and more advanced features to help you tackle even the most complex long-form writing project.

And the compiling options… so many compiling options.

If you’re a single person working on long-form writing projects, Scrivener is the way to go.

Unfortunately, it’s really not great for collaboration. And if you’re doing a project that requires complex page layouts, that’s not where Scrivener shines. I suspect most business users have never even heard of it; it’s really more of a lone novelist’s tool. But I heart it so much.

Text editors

When the technical writing gets more technical, I turn to simple text editors. Recently, I worked on some API documentation using GitHub-flavored Markdown, which I committed to a private repo on GitHub, so I used Atom for this project. It’s simple, displays Markdown and code nicely and makes it easy to spot potential problems. Atom does a good job of ‘helping’ with auto-complete and spotting properly-formed (and improperly-formed) syntax.

When I’m working on simple code, JSON, XML, Markdown, CSS or HTML, I use Atom. It’s my preferred tool when doing the more technical type of technical writing. (Until I get to more substantial code manipulation, and then I use an IDE, but that’s more developer-y and is probably an outlier for a pure writer or tech writer.)

I have friends who prefer VS Code, and my husband is a staunch Vim user… there are a lot of opinions about text editors, especially among developers. I’ll leave you all to your holy wars.

I also have a few other text editing apps I use on occasion; iA Writer and MacDown. Because you can never have too many text editors; one for every occasion!

CMS

Sometimes, I write directly in a content management system, or CMS. When I’m blogging here, for example, I just write the content directly in WordPress. When I was working for a client who had a help authoring-flavored CMS, I authored that content directly in the CMS. Same for clients I’ve had using Drupal.

I prefer authoring directly in a CMS if I’m creating rich content, with links and images, that will ultimately end up in a CMS; saves overhead vs. drafting it in a word processor, and then fighting with formatting when bringing it into the CMS from another app. (Unless I’m working in Markdown, and the CMS supports Markdown. Then I might just draft the content in my text editor.)

You’ll note I don’t have a separate section for wikis. I don’t make a distinction between a wiki and other types of CMSs; from a technical writer’s standpoint, a wiki is just another type of CMS. Granted, a wiki is supposed to encourage collaboration, so you may have more contributors, and effectively managing content there may require more process. But that’s another digression…

HATs

Some clients need a sophisticated authoring solution like a help-authoring tool, or HAT. HATs are great if you need to single-source content, create conditional content, or want to output in specific/multiple formats. MadCap Flare, Adobe RoboHelp, Author-It, and Oxygen XML Author are all HATs.

HATs are great for a single technical writer, or a team of technical writers, working to produce help documentation. Things get more complicated if you want a tool that enables easy collaboration outside of the technical writing team, such as collaboration with SMEs. More sophisticated (and expensive) authoring tools support collaboration well, too, but may add cost in terms of adding seats for SMEs, or complexity, in terms of requiring SMEs to work with docs in a specific way.

One company I’ve talked with during my interviewing process uses Flare for their authoring, which is a tool I quite like, but they manage open source projects, and they’re struggling with finding the right process to get open source documentation into Flare. The workflow they’re using is to have the technical writers manually pull in content from PRs into Flare in order to update open source docs, but this type of workaround a trade-off and something to consider when selecting tooling.

API documentation

The API documentation project I recently completed was quite simple, so I just used Atom to manually draft the docs. I’ve added a REST Client package to my Atom install, which is very basic, but gets the job done. I did install and poke Insomnia, which is a more robust REST client with a focus on documentation, but I didn’t need those capabilities for the small project I just wrapped.

On the other end of the API documentation spectrum, you have something like Swagger, which is an API development tool that also has some documentation elements, such as being able to automatically generate components of API docs, or ensuring API docs stay up-to-date as the API changes. I see it in a lot of job postings, and it’s a valuable tool for developing and documenting complex APIs.

Charts and presentations

By far the most common charting and diagramming tool I see in job descriptions is Microsoft Visio, which makes me a little sad. Microsoft products get the job done, but… well, I’ll refrain from further comment until I’m in a longer-term gig where I know I won’t have to use them. But my preferred charting tool is OmniGraffle, and it’s the one I will continue to use for my personal projects for the foreseeable future.

And then you have presentations, which, sadly, have been the bane of offices everywhere from the very first PowerPoint presentation… and will continue to be so, because sometimes a presentation (or slide deck) really is the best tool for the job. As a long-time Mac user, I prefer Apple’s Keynote, but can use either. And let’s not forget Google Slides, which is the G Suite answer to presentations.

Graphic editing, screen-capturing and video editing tools

Good documentation isn’t just words. People are attracted to interesting and engaging pictures, and sometimes a picture can illustrate a point far more efficiently and effectively than words. And video can be a great way to demonstrate a complex flow, or can serve as an alternative to documents for people who are more visual learners.

As a documentarian, sometimes it becomes my job to create or edit those pictures and graphics, capture screenshares to illustrate flow, and even create and edit video. I own and routinely use a ton of tools related to this aspect of the job, and have used many more over the years, but here’s a sampling:

There are also some great stock image sites where you can get affordable images to use in documentation; I routinely use those in my personal project sites.

Project management and issue trackers

Writing often entails some form of project management. There are a variety of reasons to use project management tools and issue trackers, from keeping track of incoming requests, to providing transparency to management about what’s in-progress, to being able to show conversations about a specific deliverable.

Most recently, I’ve used Basecamp, Pivotal Tracker, Jira, GitHub Issues/Projects and Trello for project management and issue tracking. I’m partial to Jira, but they each have their quirks, and I’m basically just a worker bee using whatever the organization uses. But I do strongly believe having one of these tools in place helps organizations of all sizes stay organized and on-top of outstanding tasks, and using this type of tool is something I look for when interviewing.

I also rely heavily on project management and issue tracking tools to provide transparency in an organization around workload and productivity. Working remotely requires an extra level of trust, and having a shared project management tool where other members of an organization can see the current workload broken down – and watch tickets progress through the columns – can help promote that trust. But there’s a whole lot more I could unpack around this… I really need to write more about working remotely.

Collaboration tools

Let’s not forget collaboration tools, whether you’re talking messaging tool (Slack) or shared workspace tools (Confluence, Notion). Collaboration is key to getting anything done as a technical writer. Maybe you’re collaborating with SMEs, or your department, or cross-departmentally among the org. Maybe you’re collaborating with freelance or contract workers.

There are a lot of contexts where collaboration tools are useful, and breaking things down to a particular level of granularity can be helpful; i.e. a shared workspace for each project, or a collaboration tool where you can lock-down access when you’re working with external providers.

I’ve used Slack in every technical writing gig I’ve had since 2016, but I’ve rarely been a part of an org that uses workspace collaboration tools. More advanced collaboration tools can speak to a maturity of process, but they can also indicate unnecessary overhead in a large organization. I always try to find out more about how these are being used when I encounter them in a workplace, because their mere presence isn’t enough to accurately telegraph a company’s process maturity.

Source control, static site generators and command-line tools

On the more technical end of things, you have tech writers set up more like developers, with source control and local development environments for compiling static site generators and viewing the output of Markdown or other text files. I generally have the command line open for using git and serving static sites as I draft them, and the occasional foray into documenting a CLI or poking a piece of software.

Some technical writers never get into this level of technical complexity; I spent years at gigs where I never had to touch a command line and there was no source control; while other technical writers I know deal with this and more complex tooling and workflow on a daily basis.

In my experience, the more tightly coupled a technical writer is with a software development team, the more likely they are to be working in this type of environment. Tech writers that are more embedded in Product, Customer Services or other parts of the org are more likely to be using software that abstracts away some of the technical complexity. But that’s obviously not true in every case; there are a wide range of ways technical writers work within an org, so it’s tough to make generalizations about tooling and workflow.

The “best” writing tool changes in context

The one generalization it’s safe to make about technical writing tooling is that the “best” tool varies based on the org, the desired output, SMEs and a broad range of factors. What’s “best” in one org may not work at all in another org. As a writer, the tools I use today may not be the ones I’ll use tomorrow; today I’m working on Markdown files in Atom and running git on the command line, but tomorrow I might be drafting a blog post in a CMS, or working on API documentation.

As a generalist, I enjoy using a wide range of writing tools; that way I can just pick up the best tool for the job when I sit down to start my task.

Real talk: freelance/contract writing

Business Writing

Real talk: freelance/contract writing

Someone in the Write the Docs Slack was asking about things to consider as she pondered transitioning to a freelance/contract technical writing career, and I have Thoughts to share:

Benefits and administrative overhead

Freelance/contract typically means 1099, which means no benefits – no insurance, no matching 401(k), no PTO, and you do your own tax withholding and paying. These things have a real dollar value, so it’s worthwhile to consider what your rate needs to be to make up for the cost of losing those benefits.

Additionally, taking care of these tasks require a lot of administrative overhead that eats into your working time, especially when you’re just starting out and figuring stuff out. So if you want to work a 40-hour week, you may end up working 45-50 hours for a while as you spin up on new knowledge and processes.

Marketing

You have to be good at selling yourself and your services. This can feel unnatural at first for some people, and if you’re someone who doesn’t like doing that, you may not enjoy the process. You will likely spend a lot of time when starting out figuring out how you want to position yourself, tweaking website/resume copy to appeal to the clients you want, how to screen for clients that are likely to respond to your particular style/skills, etc.

When I first started freelancing, I spent anywhere from 10-20 hours weekly looking for/applying for projects, on top of any hours I was actually working. YMMV, obviously.

Work availability

In terms of working on things you’re passionate about… when you’re doing freelance/contract work, you may not always get that luxury. It’s very feast-or-famine. You may have a lot of work availability at once, or you may have months where you don’t have any projects going on. When you haven’t had anything in the pipeline for a while, you may be more likely to go after projects that don’t excite you just to have some income.

Making your own schedule

Re: making your own schedule: freelance offers some flexibility, but especially if you’re doing contract work, the client may expect you to work a regular 9-5 just like you were a corporate worker. In a lot of contract gigs, you’re expected to behave/function like a company employee, report on-site during regular hours, etc. – so it’s kind of like being an employee without the benefits, and typically on a temporary timeframe. If you’re doing a project-based gig vs. a contract, you may have a little more flexibility in making your own schedule, but there are also fewer of those.

Pitfalls of the freelance/contract world

There are serious pitfalls possible in the freelance/contract world. There are clients who slow-pay, or never pay at all. (The latter has only happened once to me, but I have had clients drag out billing for months; I’ve fired a few clients for this reason.) I’ve landed gigs, only to have them get canceled at the last minute, and then I have nothing to replace them. Exactly twice, I’ve gotten into a gig, only to find out that the client’s expectations were completely unreasonable and the gig wasn’t going to work out. Bail early in those situations, and I’ve learned to better screen my clients to make sure we’re aligned before starting a project.

Screening clients

First and foremost, I look for a client who either has a strong idea of what they want, or is open to letting me lead the process as the expert; someone who doesn’t know what they want but wants too much control can be an issue. I look for how reasonable their expectations are. Is their project far too vast to accomplish in their stated timeframe? Are they in love with a specific toolchain that isn’t well-suited to their project? Are they flexible in their approach? I start with general questions and then follow up with specifics based on their answers to get a feel for how it would be to work with them, and whether I think what I can deliver will align with their expectations.

In terms of slow-pay and no-pay clients, I look for level of professionalism. Are they an established company, a startup, or someone with a side project? Do they ask for a W-9? Do they have other vendors? How wide is their online scope? If it’s a pretty big company that regularly works with vendors, they probably already have a fixed contract they use and they’ll ask for a W-9 (in the US anyway), and you can probably rely on them to pay – although it may be slow. The issues I’ve had have been with smaller companies, companies that re-org or individuals with side gigs, so I’m a bit more wary about those.

Contract pitfalls

As a freelance/contractor, you typically will not own rights to the work you produce. If it’s public, you may be able to point a future employer at it, but if it’s proprietary, you will not be able to show your work to future employers. This can become a major bummer when you’re hunting your next project/gig – I’ve done some awesome work I can’t show people because the IP belongs to the client. I even wrote a blog post about it a few months ago.

Beware of contracts that generically state that work you do/writing you produce while working for X becomes the property of X. I’ve seen really generic clauses that could apply to work you do outside of the client’s contract while you’re also contracting for the client. The most recent contract I signed had language specific to the work I produce for the client belongs to the client, and work I produce outside of client work is 100% mine, and I’ll be ripping off that language for every future contract.

(Also, when contracting, typically the employer provides the contract; you may get to suggest changes, but usually it’s a pretty fixed thing. If you’re doing stuff on a project basis, or more casual work you pick up from word-of-mouth or off something like a Craigslist, you may have to provide a contract.)

Finally, there’s legal liability. There’s one client I worked with that had language in the contract that said any legal liability for the content I created was my responsibility. i.e. if someone got injured following my directions, I was legally liable, not the company publishing/providing the content. Don’t sign those contracts. You do not want to assume legal liability for some jackass out there who injures himself using a hammer – or a more complex, dangerous power tool.

Where to hunt for freelance/contract work

This has changed for me over the years. Back in the day, I did a lot of work on Elance, which then became oDesk… I don’t know what it is now. I’m also very public about being a writer/tech writer, and have had work come to me from my personal network.

Over time, I got a stable pool of clients, and those clients would recommend me when people they know needed a writer, so I stopped going out looking for work because so much was coming to me. That was probably 2-3 years after I started freelancing.

More recently, I spent two years in a full-time gig, and then took some time off, so I only recently (this year) spun up the work hunt engine again. This time, I’ve found my engagements via Slack. I’ve applied for a lot of things on job hunting sites – LinkedIn, Indeed, Dice, ZipRecruiter, WeWorkRemotely, and have had mixed results with those. I got a couple of offers but they couldn’t meet my rate requirement, but I also got a lot of screening interviews where I never heard back from a hiring manager.

It helps to have strong samples, and be able to speak authoritatively to process; I’m currently working on an open source project in my free time, so I can show examples of my API work when my current engagements finish.

Finally, YMMV but there’s a freelance developer on a Slack where I’m a member, and he routinely posts queries he gets from his Craigslist ads (developer offering services) when he doesn’t have the bandwidth to do them himself, so there may be some traction there; I’m not sure.