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.

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.