TechWriter at work blog

Living and writing documentation at Documatt, small team of programmers that write documentation too.

---

Editor skills of every tech writer

Know and love your editor. Programmers and tech writers literally spend their lives in powerful text editor and IDEs but sometimes aren’t aware of all their editing features. In the following post, I share some essential skills you, as a tech writer, should definitively adopt.

All programmer’s editors and IDEs offer similar functionality. But screenshots, videos, and keyboard shortcuts I will show in the post are from JetBrains PyCharm. Let me know in comments how to do it in your favorite editor! I will update the post.

Column selection mode

How?

• JetBrains IDEs: Alt-Shift-Insert or dragging vertically while pressing Alt-Shift

This is one of the coolest productivity hack. Normally you select lines horizontally. In column selection mode, selection works vertically. How is it useful? Actions taken in this mode are repeated in multiple places at the same time as you edit.

The situations where column selection shines the most is, for example, transforming bullet list in Word to reStructuredText list table. Let’s look at how many strokes I saved:

Vertical rulers

How?

• JetBrains IDEs: Visual guides field in File / Settings / Code Style

Many teams have some kind of code style guidelines. They usually dictate maximum line length. For example, Python PEP 8 requests 79 characters. Other usual values are 80 or 100 characters.

Editors allow specifying several rulers - for example, at 80 and 100. Rulers may also be called visual guides etc. They look like this (those two thin lines at right – enlarge the figure):

You can also set editor to hard wrap at ruler as you type:

Wrap to column

How?

• JetBrains IDEs: builtin Edit / Fill paragraph is buggy, I recommend Wrap to column plugin.

This action (also called “fill paragraph”) wraps the paragraph at the certain column. Useful mostly for reformatting existing files.

Join lines

How?

• JetBrains IDEs: Ctrl-Shift-J

Join lines does the opposite of wrap to column - it removes newlines and creates paragraph from the selection.

Marcos

How?

• JetBrains IDEs: File / Settings / Editor / Live Templates

Do you write long or difficult-to-type phrases again and again? Most editors and IDEs allow creating your custom macros that insert a boring text using few keystrokes.

For example, in technical documentation written in reStructuredText, I often need to type fragments as

:guilabel:`This is GUI label`
:menuselection:`File --> Setting`

For example to insert :menuselection: I type only ms and press Tab.

In JetBrains IDEs macros are called Live Templates.

  Next: Pictures in documentation best practices

Comments

comments powered by Disqus