June 2013 Meeting Discussion: Low-Friction and High-Velocity: Information Delivery in the Age of Interaction

Presented by Dee Elling and her colleague Pamela Clark, and reviewed by Kelly Hong

Startups–A Brave New World for Technical Writers

For the past two years, the technology industry has been booming in San Francisco, with South of Market (SOMA) and the downtown area being the fertile grounds for software startups. Every month, we hear about yet another startup sprouting up from someone’s garage, and turning into the next hot tech idea. And all these startups are driven by passionate software development teams eager to turn their new idea into the next hot mobile app or software as a service (SaaS). These vibrant small companies are often in need of technical writers to help them document their products for internal use, customer communication, and more. Any technical writer looking to work at a startup, or currently working for one, should be aware of the existing industry trends their fellow tech writers are seeing.

That is what Dee Elling and her colleague Pamela Clark talked about at the STC-SF June meeting. The growing trends they see at today’s software startups, how it has affected documentation and what it’s like being a technical writer in such an environment.

First off–most if not all software startups use Agile development. Meaning software is planned out, designed, coded tested, and released in a short period of time (often weeks, not months.) In order to accomplish this, teams work simultaneously and continuously, collaborating face-to-face and focusing on delivering functioning software to clients and share holders.

Fast communication, responsiveness, and adaptability are valued over comprehensive processes and documentations. (See agile manifesto) For technical writers, that means you are in an environment where everything moves super fast and is in constant flux–such as product requirements, user interface, features and functionality of a product, etc. What you wrote yesterday may be out of date today.

Therefore companies are often a flat hierarchy where there are not barriers to access information or personnel. Anyone, regardless of title, can walk right up and talk to each other. Interns can chat with the CEO; engineering can talk to sales and so on. This is called a high-touch environment, where you are free to talk to anyone but they are also free to talk to you. Information is easily accessible, but interruptions are very common. To get a solid block of hours to really concentrate on tasks and projects, people often have to work from home or wear headphones.

To thrive in such a fast pace and often hectic environment, you need to stay flexible. It is an exciting, high-energy environment, but also hectic and often disorganized. Companies can encounter scalability issues because they are growing incredibly fast, pushing out products just as fast, and not dedicating time to polish up products, do maintenance, or documentation. This can lead to efficiency gaps, lost knowledge when key people leave the company, and code that breaks consistently.

Technical Writing: Old vs. New

In the past, enterprise software was built for large business and government organizations and designed with cumbersome ‘ugly’ user interfaces (UI). But today, many enterprise companies are now focusing on consumerization, by designing software with the consumer in mind with UI designed to be easily usable by any user familiar with using a web browser to access the internet.

Software systems also used to be more simple architecture wise, with only a few applications and servers. Now they are intricately complex with multiple parts not always owned by the same company, often integrating third party software, and often being updated without notice. This change in software development is the new reality.

  • Contrary to what TW are used to, now most technical writing comes at the end of the release cycle when users give feedback and are using products and finding unforeseen use cases & reporting bugs. Procedural steps are less desired. Companies want more scenarios and use cases–“John has set up his account like A by doing B.”
  • All writing is done on a wiki such as Confluence and rarely as offline Word documents.
  • GUIs now have more embedded user assistance and intuitive UI. Thus engineers and Software Developers are being asked to document their work and now own the GUI design and help text. Meaning tech writers no longer have to write UI text, steps, and summaries.
  • Writers cannot anticipate all use cases and need to get used to writing documents after release cycles which have now shortened to usually two weeks.
  • You are more visible and accountable for what you write.

Writing Tips

  • Accuracy of information is no longer as important as a quick response to a customer’s question. If you find yourself limited on time, it’s okay to repost information from subject experts or other customers without validating its accuracy because information can be easily updated; and customers know that.
  • Pick your battles, because you can’t win them all and some decisions are out of your hands.
  • Do the best you can, but there is no finish line. So set you own boundaries.
  • Formatting rules are not as important as being comfortable with the tools you are using.
  • Try to organize a wiki into sections: Customer-facing, internal, partner, post-release, and prerelease.
  • Everything is an evolving processes, so stay calm and find where you fit.
  • Everything you do matters and you receive immediate feedback.
  • Get best info from people using product, not the ones who wrote it.
  • When you have backlog of things to write for releases save time by writing only as far back as the last release.

Overall the talk was a good glimpse into what it’s like being a technical writer in the software startup environment and the energy and culture they encounter on a daily basis. And was a good heads up for writers interested in working in the industry.

Kelly A. Hong has a B.A from SFSU in technical writing and currently works as a QA engineer at a C2C Consumer referral startup software company in SOMA. These days, she does more software testing than writing, but still loves writing.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s