4 Tools for Writing Documentation

How do you document your projects? Do you keep a programmer’s notebook? As you write code, you will have ideas, notes, code snippets and other things that you have learned. You’ll want to keep code that you didn’t use and save for later. By keeping a programmer’s notebook, you’ll create a personal reference that you can use for other projects and documenting your code for your users.

4 Tools for Writing Documentation
Photo by Jan Vasek

What tools do you use for writing documentaion?

You can use pen and paper to create a bullet journal or collect your notes and ideas. If you want to use an app, I have collected 4 tools that you can choose from.

Boostnote

Boostnote is a note taking app for programmers. You can take notes and collect code snippets. Boostnote is customizable and usable anywhere. You can write notes on your laptop and share with your mobile devices.

Bootsnote App

Quiver

Quiver is a programmer’s notebook. You can mix code, text, Markdown in a note. You can install Quiver on your Mac and iOS devices.

Quiver app

Bear Writer

Use Bear Writer to create notes and prose. You can organize your notes any way you can. This app is available on your Mac and iOS devices.

Bear Writer

Write the Docs

Write the Docs is an open source community dedicated to creating wonderful documentation. They provide guides on writing great documentation, conferences and meetups. Write the Doc is build using the Sphinx static site generator.

Write the Docs

Whether you use pen and paper or an app to document your projects, you’ll have a reference that can help you better understand the problems, solutions and things you have learned. Writing documentation for yourself or your users makes you a better programmer. If you want to write better documentation for yourself and your users, Mark has collected tools and resources for creating great documentation.

Improve Your UX with Microcopy

What is microcopy? It is the smallest piece of content on your website or app. Microcopy can be text-based or visual. Text-based includes buttons, calls to action, error messages and forms. Visual microcopy focuses on images and videos.

Improve Your UX With Microcopy

Microcopy needs to be easy to understand, short and draws the user in. It should guide the user and help them to understand how to use your website or app.

What can you do to improve your microcopy?

Talk to your users like a person

Does your copy sound conversational or like a marketer? If it sounds like a marketer, change the words. You want to write copy with the same words that your users use.

Use copy to guide your users

Write short and helpful sentences, not paragraphs. If you need more than 8 words to explain what the users need to do, rewrite it.

Explain errors

Nothing is more annoying than confusing or cryptic error messages. Let your users know how to fix the problem. Take the time to write simple and easy to understand error messages.

Minimize User Worries

Your microcopy should anticipate user questions. Use clear labels and descriptions in forms to minimize data entry problems. Let them know why you require certain pieces of information.

Know when to user your Brand voice

Your microcopy can use your brand voice. The trick is to know when to use it and when not to. Some situations require clear and simple language.

Want examples of good microcopy?

Goodmicrocopy.com, curated by Richard Sison, has a collection of clear, concise and sometimes quirky microcopy.

Screenshot Good Microcopy.com

When you create a website or app, the smallest bits can make your users’ experience a good one. To make their experience a good one, remember to design the smallest bits of microcopy.

4 Items to Include in a Development Tutorial

Writing a tutorial is a good way of sharing how you solved a programming problem. Programmers use tutorials to learn how to write the code for themselves instead of depending a all ready written code. Tutorials can be a quick way to learn how to do something. What do you need to write a good tutorial?

4 Items to Include in a Development Tutorial

4 Items to include in a tutorial

  • Step by step instructions
  • Screenshots
  • Code snippets
  • Version of software or tools

Step by step instructions

By providing step by step instructions, you can break the tasks down into easy and understandable pieces. Your readers will be able to follow what you learned and do it themselves.

Screenshots

Sometimes, steps aren’t enough. You need to show your reader what happens. A screenshot can show you what to expect, look for or do. A good screenshot compliments what you want your reader to do next.

Code

Make your code samples easy to copy and to understand for new and experience programmers. You can use a tool like CodePen.io to include your code. Or use one of these 4 Ways to Add Code Snippets.

Version of Software or tools

Your software and tools change over time. New versions come out. Let your reader know what version of the software that you were using.

What about video?

Not a writer? You can record a video tutorial instead of writing one. Gregg Pollack on Hackernoon collected 10 Tips to create the best worst programming tutorials. If you prefer video, keep these tips in mind so your video tutorial isn’t the worst.

Summary

Writing a tutorial can help you to understand a new concept or programming problem thoroughly. Use these items to help explain what you have learned. When you teach others, you learn new things about the concept that you are teaching.