Write Better Documentation for Your Code

Do you write documentation? Most developers love to write code. They write code that solves problems. It helps people to get something done. If they write documentation, it is quickly written. A task to be completed so you can get back to writing code.

Write Better Documentation For Your Code
Image by Christine Sponchia from Pixabay

How do you choose a new framework? You look at the features to see if it does what you want. Then, you read the documentation. If it is hard to read or non-existent, you’ll get frustrated and choose a different solution.

If you want people to use your code, you need to write great content.

How do you write better documentation?

  • Decide who you are writing it for
  • Decide what you are going to include
  • Make it easy to use
  • Keep it up to date
  • Read great documentation

Decide who you are writing for

You need to know your audience. Are they developers, clients or customers? Developers want to know how to use your code. Or what can they do with it. Your clients may want step by step instructions on how to use it.

What are you going to include

Decide on what you want them to know. Create a list of questions or items that you need to cover. A technical audience may want to read tutorials, how-to-guides and/or references. Beginners learn better with simple step by step instructions. For everyone, you may want to include videos as well.

Make it easy to use

No matter what you are writing, decide how you are going to organize it. If you are writing a tutorial, you may want to start by explaining what you are planning to talk about. Use formatting styles like headings, bulleted or numbered lists and bold or italics. Formatting styles help guide the reader through your documents.

Keep it up to date

Developers make improvements and changes to their code. When they do, the documentation needs to change as well. Plan time to update it. Apps and other projects fail because the content isn’t kept up to date.

Read great documentation

You can learn how to write better by reading. These style guides show you how to write great developer content.

More Resources

What tools do you use for creating great content?

What tools do you use for creating great content? Writing is challenging. When you need to write for the web, the pressure to create and publish great content makes it even harder.

What tools do you use for creating great content?
Photo by Peter Pryharski on Unsplash

You can choose to start writing. Force yourself to start with an idea and a blank page. Which may result in not so great content. Or you can use a tool or framework to plan out what you want to talk about.

You can use simple tools like mindmapping or an outline like you used in school to write an essay. These are great tools for getting started planning. For some types of writing, you are going to need a different technique.

  • The Core Model
  • Content Framework
  • Pair Writing

The Core Model

What is the Core Model? It is a tool that helps you to map out your business goals, user tasks and context. The Core Model is useful in deciding how users find the content you are planning and sketching out the main content. It helps you to focus on your business goals and user needs before you start writing.

Content Framework

The Content Framework is a form that you can use to answer questions that are vital to the writing process. Questions like who is going to read this, what business goals does this page support, and what tasks do we want the user to do. It helps you do think about what you want to say and who is your audience before you start writing.

Pair Writing

What is Pair Writing? It is borrowed from an agile software development technique called “pair programming“. In Pair Programming, two programmers work together on writing code. One programmer writes the code while the other one reviews it. The second programmer offers suggestions for improvements. The two programmers frequently switch roles. This technique takes longer but generally produces better quality of code.

Pair Writing follows a similar pattern. One person writes while the second person observes, asks questions and provides suggestions. The two writers switch roles to take turns writing and offering suggestions for improvements. This technique can take longer but you get greater involvement from all members of your team.

Writing for the web is challenging. When you have a team of designers, developers, content writers and management, using a writing process like The Core Model makes thing easier. It helps you to plan out your goals, answer questions on what the content should be about and do and create content that focuses on your customers.

Moving to Markdown

What is your writing process? Whether you write a blog or technical documentation, you need to have a process. Not just a writing process, but a process for getting your work in a format that can be published on the web. My process is writing, converting to hypertext and publishing. It works, but it can be cumbersome adding the html code to my writing. What can I use instead? Markdown.

Moving to Markdown
Photo by: Free-Photos

What is Markdown?

Markdown is a way to write for the web. It is text to html conversion tool. The goal was to make it as readable as possible without looking like it was marked up with a bunch of formatting code. This simple system was created by John Gruber.

When you write HTML, it can get very complicated looking with the tags and extra formating:
HTML Code Screenshot

With Markdown, it looks much simpler:
Markdown screenshot

Changing your writing process

Markdown is easy to learn. The syntax is very simple. In five minutes or so, you can start writing in Markdown. You can use either a text editor or an app for Markdown.

What if you don’t want to use a special app? You can install it in IDEs like Atom or Visual Studio. With an IDE like Atom, you can use the preview mode to see how it will look in a browser before you publish your writing.

Want to get started learning Markdown? Start with this Markdown tutorial. It goes through each concept one lesson at a time. You can also use this cheatsheet to look up how do write Markdown.

Tips for UX Writing

What is UX Writing? It is the practice of writing copy that is used in user interfaces to guide the user and help them figure how to use the website or app. You write your copy to ensure that everything matches the tone and style of your brand. Microcopy is the small pieces of copy that helps the user get stuff done. These little pieces are typically error messages, button text, helpful hints, notifications and more.

Tips for Ux Writing
Photo by Sarah Pflug

Why UX Writing?

It affects how the users interact with the UI. Good copy makes the user interface easier to learn and to use. It guides the user on what they need to do and doesn’t interrupt them. Bad copy ruins the experience for the user. It makes it harder for the user to learn and use the UI.

Tips for Good UX Writing

  1. Have a conversation. Talk to your users. Avoid writing robot-like messages. Use words like “you”, “we” and “our”.
  2. Keep it simple. Be brief and avoid complex technical jargon.
  3. Don’t be too quirky. Trying to be fun and cool can backfire. Use it sparingly.
  4. Test your copy on a variety of users. If they are having trouble understanding or using the UI, you need to change your interface or simplify the copy.
  5. Reflect your brand. Make sure your copy matches your voice and tone. Refer to MailChimp’s Content Style Guide for tips on writing for your users.

Copy is an integral part of your UI. The copy should guide the users and be unnoticeable. Good copy improves the usability and functionality of the UI. It helps a user to intuitively understand what they need to do. If you have to explain your UI, it isn’t done right.

More Posts on UX

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.