Shortcuts for Writing technical docs in 30m or less

…so that I can get back to what I’m paid for: writing great code.

tl;dr Summarize (in a tl;dr section like this!). Use great free tools to get screenshots and visual aids. Use keyboard shortcuts and your copy/paste buffer efficiently to avoid intermediate files whenever possible.

Too Long; Didn’t Read
The purpose of a tl;dr section is for both you and the reader. It gives you focus. It gives the reader quick information about the value of they’ll get for spending their time.

Break it up with Screenshots, Graphs and Diagrams
Would you rather read the document on the left or the right?
Screen Shot 2017-05-12 at 10.25.55 AM Techincal

‘Nuff said.

Avoid Intermediate Files
It used to take me a long time to create nicely presented documents, but the trick is to learn keyboard shortcuts and your use copy/paste buffer like crazy.

I’m on a Mac. If I need a simple screenshot or image from the web, I use ctrl + cmd + shift + 4. That brings up a cropping tool where you can capture a segment of the screen directly to the copy buffer.

In Windows 10, use windows + shift + s. In older versions of windows, use the built-in snipping tool.

snippet tool

Most documentation systems, Confluence included, now allow you to just hit cmd + v and paste your image directly into the document.

Spice it up with Graphs
If you have some data, I recommend getting it into google sheets and hitting the explore button in the bottom right corner
Screen Shot 2017-05-12 at 10.26.17 AM
Check out the awesome graphs you get (with literally no work).
image of diagrams and graphs

To get the shot above, I simply used thecmd + ctrl + shift + 4 trick, and pasted it into this document.

Use Diagrams
If you’re lucky enough to be using Confluence with Gliffy installed, you can simply click this button to add a diagram inline:
gliffy in cofluence

I’ve recently been using Dropbox Paper for documentation, which doesn’t have a Gliffy integration yet. So I simply take a screenshot and paste it into my doc:


Tip! I like the Gliffy gridlines, but you can turn them off using this button:
gliffy toolbar button

That’s It!
Without much hard work, I can make my technical document readable, visually appealing and informative.

Rocco is a former Gliffy employee who still uses the product daily. He is offering a video course about becoming a Google Chrome Devtools expert at a massive discount for Gliffy readers. You can visit his website for a free short course on DevTools.