• August 2019
    S M T W T F S
    « Sep    
  • Facebook

Posts Tagged "beginners"

Question: What qualities should technical writers have to work at startups?

Question from recruiter

A recruiter recently asked me what traits technical writers should have for startup companies. Startup environments post unique challenges when it comes to technical writing. Here are a few thoughts about the characteristics technical writers need to succeed in this environment.

1. Technical aptitude

You need to be strong enough technically to select and implement the appropriate tools for the technical writing tasks. At a startup company, you will likely need to decide on the authoring and publishing tools and workflow, get support to make purchases, and then implement them all by yourself.

You won’t just be plugging in to an existing framework, usually. Or if there is an existing framework (e.g., Google Docs), you might need to transition it to a more robust and mature publishing model.

2. Independence and leadership

You’re often the only technical writer at a startup, so you need to be able to be comfortable working independently. At the same time, you need to be outspoken and bold enough to teach others at your company about how technical writers should integrate into the software development lifecycle, how technical writers fit into the organization hierarchy and groups, how the review process should go, and so on.

You have to train the company about how they should work with technical writers, because often they won’t really know where, when, or how to work with you.

3. Content strategy skills

You have to see the larger picture for the projects you’re documenting. What kind of content do customers need throughout the customer journey as they interact with the product? The startup probably has disjointed documentation and marketing materials written by various people with different messages and emphases, with varying levels of accuracy.

You should get a handle on this information and identify gaps, rally people to align with common messaging, terms, and style, and generally see the big picture to create documentation that serves the entire customer journey.

4. Versatility

As the only technical writer, you’ll probably wear a variety of hats. As such, you need to be able to write different types of content beyond just documentation. You may have to prepare marketing materials (white papers, use cases, conference materials), you may play support roles (responding to forum posts or other questions), you may be involved in social media (blog posts, Twitter, and awareness campaigns), you may write internal documentation (AWS setup, networking diagrams, etc.), and more.

5. Stability

Startups are wild rides. When the startup gets funding and money is in the bank, everyone is happy and full of optimism for the future of the product and company. There’s a rush of good energy and forward momentum.

However, when the product fails to generate the revenue promised to the investors and stakeholders, startups start rebalancing personnel, shifting product emphases, laying off some people and hiring others. When the business goes south, it may fizzle in a couple of years. As it declines, other employees start leaving in a steady exodus.

To ride the roller coaster of a startup, you need to have stability in your career, knowing that if your job dries up you can find another, or that you have savings to cover a period of unemployment during the transition, or that you can handle any changes and continue with the company perhaps in another role entirely (e.g., support or training manager).

Back to Top | Comments Off on Question: What qualities should technical writers have to work at startups?

Podcast: The divide between academics and practitioners — Interview with Lisa Meloncon

Here’s the audio for the podcast:

You can download the MP3 file here.

Podcast summary

One common response I usually get with podcasts is that people want a transcript of the audio. Although I don’t have time to make a verbatim transcript, I decided to write out a brief summary of notes and highlights (based on what jumped out at me during my own listening) in a more informal way this time. Here’s the summary:

Tell me a little bit about yourself.

Lisa Meloncon started out writing technical documentation for missile guidance systems for the U.S. Army. When she left the army, she stayed in tech comm and started her own company in 1994. As a consultant, she solved communication problems at many different types of organizations. Later, she returned to school for a PhD and, after completing her program, pursued an academic job. As a professor, she does research, teaching, and service. She loves teaching and brings her research into the classroom in energizing ways.

Why did you decide to get into the academia and do research?

There were some things that were driving her crazy in the field, one of them involving questions of document design. One client wanted reports with bullets only, and no independent sentences. She couldn’t convince him, and she felt that an academic program and research would give her information to persuade clients like this and many others about best practices with tech comm.

How do you get academic research out to practitioners?

It’s extremely hard. The paywall is an enormous barrier. But this is simply how publishing is done in higher education. It really falls on the academic to try to get the research out there in another way.

However, publishing outside of academic journals doesn’t have any rewards for the academic, except for falling into a general service category. As a result, academics just don’t have the time, energy, or money to rework and publish the content in other formats.

Do journals retain publishing rights over the articles academics write?

It depends. Sometimes journals allow academics to publish the articles for educational reasons. Or if the journal makes a special exception (maybe you’ve won an award), you can sometimes republish. But by and large, journals control access to the content in ways that make it difficult for practitioners to access.

Even with journals that are accessible (like the Technical Communication journal), practitioners often don’t read the articles that they actually have access to. Why?

If practitioners don’t read the journal because they find the content irrelevant, remember that these journals can only publish the content they receive. This content has to go through peer review by an academic and practitioner. The reviews may be at odds with each other, which complicates the editor’s job.

About 19-25% of submitted articles get accepted. Although the articles in the Technical Communication journal follow a traditional academic style, the Technical Communication journal actually does publish practitioner takeaways that summarize relevant points for the practitioner. The Technical Communication journal is one of the few journals to do this.

As for the academic writing style, this style is entrenched in the discipline of academic publishing. When Lisa first got into academic publishing, she had to change her style dramatically. It was painfully difficult for her, but she would have never published anything had she not taken a more academic tone and approach.

Although practitioners are turned off by the academic writing style, in order for academics to excel in their field, they have to publish this way — in academic journals with content written in a thick academic style. There isn’t much incentive for the academics to publish outside of academic journals in online sites with a more popular style. There is some reward giving to service when you publish, but it’s not significant in comparison to the academic publishing.

Larry Kunz recently published a blog post titled What should a Technical Communication course teach?. Though Larry doesn’t mention it, he covers a similar topic as Miles Kimball’s article, Training and Education: Technical Communication Managers Speak Out, in the latest issue of Technical Communication journal. Miles’ conclusion is that managers want people skilled in the fundamentals of technical communication rather than specific tool knowledge. Hence tech comm programs should focus on writing and editing, not so much tool knowledge. Do you agree?

Well, the research in the article was based on a small number of managers and isn’t so general. But many job ads do list tools as requirements. So tools are important, but the problem is that the tool taught in a program may not be the tool required by the job market. The tools used by different companies are really diverse. A lot of times when teachers teach a tool, the students get caught up in this tool and then become hesitant to learn or embrace another tool.

This tools question is a really constant scenario that people run into. These technologies aren’t cheap. So many of these jobs seem to require knowledge of Adobe products. When Adobe moved to their cloud subscription model, this increased the cost of the tools five-fold.

Students often come in and say, I see all of these tech writer job ads requiring tools … so where’s the Framemaker course? Teachers constantly have to explain why there isn’t one.

Programs have a difficult time making the subscription model work for students. Students may have to buy 3-4 different subscriptions for different tools, which adds up to a lot more than a book. Consequently, programs look for open source alternatives that approximate a similar experience.

A lot of practitioners form communities around tools. Is the lack of focus on tools one reason why practitioners don’t find academic journals relevant?

Possibly, but access is also a huge issue. And sometimes it’s hard for practitioners to see how an academic journal is relevant to their jobs. It requires more time to really sift through the content.

Was the most recent Technical Communication journal, whose focus was on “How a few great companies get it done,” specifically trying to be more relevant to practitioners?

Not necessarily. The issue looks at what’s going in these great companies. It shows the types of research that can be done, but it wasn’t conceived as an attempt to bridge the academic-practitioner divide.

The research for this issue took 2.5 years. Good research takes a lot of time.

Why does it take so long to complete the research?

Access to the information is one problem. It also takes a while to come up with the best way to answer a question. Research has to be rigorous or it’s not going to be get published.

One of the reasons Lisa was successful as a consultant was her ability to go good research. Her pet peeve at conferences is seeing people present information that is based on poor research.

The research element is a huge dividing factor separating academic publications from non-academic publications.

However, Lisa doesn’t discount articles that aren’t based on more rigorous research. Lisa says that the non-academic publications provide academics with preliminary data, which can then be leveraged in more rigorous research.

One of the questions in the latest TC journal is whether tech writers should be specialists or generalists. The research in the journal suggests that generalist skills form the core identity of tech writers and allows them to play more roles throughout the product life cycle. The journal used a Delphi method with iterative surveys. Is this the best way to go about the research?

You need to start as a generalist, but if you’re ever going to advance, you have to specialize. Lisa’s specializations, especially her geography and environmental science knowledge, helped her advance in her career.

*Which is more persuasive to practitioners — the academic approach or the practitioner approach? Does all of this rigorous academic research really matter to practitioners?

When you’re a consultant, research can be key to your survival because you constantly have to argue for the positions that you take. Consultants have to leverage the research to make compelling cases.

Rigorous research also helps us avoid repeating history. There’s definitely value to knowledge, but you may value different types of knowledge.

Additionally, there is sometimes a contradiction between specialized, authorized knowledge (based on your own experience at different companies) and generalized knowledge (based on academic research).

The research in the journal gives you validity and authority to persuade clients. Anecdotes are a single data point, but not enough to persuade people to make decisions that have millions of dollars attached to it. If you match the research to the organization’s goals, it provides a strong case.

How can we bridge the divide between practitioners and academics?

Academics can be more public in their work. If given more assistance, academics might write more blog posts. Academics can put out practitioner versions of their research.

Practitioners can participate when asked to complete surveys and provide other feedback and information.

If there is data practitioners want, they should ask academics. This can help academics focus on research that they should do.

Overall, there does need to be more exchanges between academics and practitioners, especially at conferences. We need to be showing up at others’ places more regularly. We have to be talking more to each other in different locations.

Practitioners should also respect academics more, recognizing that the job academics do is different and unique. The sense of value practitioners have towards academics will increase as practitioners see the value of what academics write.


Back to Top | Comments Off on Podcast: The divide between academics and practitioners — Interview with Lisa Meloncon A new online learning resource for DITA by Scriptorium

A Free Course on DITA

One common question I receive from people on this site is how they can learn DITA. Scriptorium has published a new online course (their first, I think) called The first course available is “Introduction to DITA.” is a free online resource created by Scriptorium for learning DITA

About the course

The course is well-organized and oriented for beginners. Here are some general characteristics of the course:

  • The course is primarily text-based, but there are about half a dozen short 1-minute videos peppered throughout. (I could hear Sharon Burton’s voice in the videos.)
  • After each lesson, there’s a quiz to test your knowledge. The quizzes aren’t hard, but if you don’t pass, you must retake the quiz in its entirety. (If you get a wrong answer, an explanation of the correct answer appears.)
  • There aren’t many mentions of tools, but when there is mention, OxygenXML is noted briefly. (Oxygen is one of the site’s sponsors.)
  • There are links to additional learning resources (often to the DITA Style Guide) for each lesson.
  • Some of the questions involve drag-and-drop activities to match topics with descriptions. (I liked the interactivity of the drag-and-drop.)
  • The course lasts about an hour. Some of the concepts covered include topic types, tables, links, relationship tables, conrefs, and maps.
  • When you finish the course, it just shows all modules being complete. (You don’t get a certificate or anything, which is what a lot of new technical writers want.)

Who created the course

Multiple contributors put together the course. From what I could tell, the main contributors included:

  • Simon Bate
  • Sharon Burton
  • Sarah O’Keefe
  • Bill Swallow

What the course is built on

The content for was developed using the DITA learning specialization. As explained on the About page:

The content is written in DITA using the DITA learning specialization. runs on WordPress; we created XSLT transforms to publish the content here.

It’s interesting to see that Scriptorium created XSLT transforms to publish DITA to WordPress. I think that’s a great example of publishing DITA content.

Overall feedback

My overall feedback about the course is that I thought there should be more hands-on activities. People primarily learn by doing, so there should be more activities that help people create the content talked about in the course.

To credit, there is a lesson that shows how to create a topic in Oxygen, but that’s it. I think there should be a walk-through from beginning-to-end on how to get a simple DITA project authored and published.

Most of the information needed to create a project is provided in the course, more or less, with easy code samples that one could copy and paste. But it would be nice to see an actual step-by-step tutorial for executing a project inside Oxygen or some other tool. Since this is just the “Introduction,” maybe a future course will provide this detail.

Why am I reviewing this course?

If you know me, you may wonder why I’m reviewing a course on DITA, since I abandoned DITA for Jekyll some months ago.

Well, I’m interested in seeing different approaches to online courses and learning. Whereas Peter Gruenbaum’s course on API documentation was primarily video-based, the course is primarily text-based.

Also, I’m trying to highlight more newsworthy events on my blog, and this course on DITA is a first of its kind. Congrats to Scriptorium for making this information available for free on the web.

Back to Top | Comments Off on A new online learning resource for DITA by Scriptorium

Other Stuff