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

Get Data Using JavaScript Fetch API

I was looking for a simple to get data from an API. When I found this tutorial using JavaScript Fetch and the Random User API. You use Fetch to send a simple GET request to the Random User API and provides you with JSON data of 10 random people.

Get Data Using JS Fetch API
Photo by Shopify Partners from Burst

Why manually type in code?

In Learn Ruby: The Hard Way, Zed A. Shaw, explains that you must type in the exercises by hand. It helps you to learn how to read, write and see code. By using copy and paste, you don’t learn how the code works.

How do I used this tutorial

This site is simple. I started with a simple HTML site. Then, I made some adjustments after I got the GET request working.

1. Added style to the website
I started with a simple HTML website that didn’t have much style to it. First, I added CSS code to style the images. Then, I added a header and footer to the site. I decided to stick with a black and white color scheme.

2. Changed how the API displays the data
When I first created the site, the API returns the user’s name in all lower case letters. I wanted the name to follow the format of first letter upper case and the rest lowercase for both first and last name. I modified the JavaScript to capitalize the first letter.

function capitalizeFirstLetter(string) {
    return string.charAt(0).toUpperCase() + string.slice(1);
}

The API returns the email address as text only. I wrote an additional function to change email to be an actually email link.

function createEmailAddress(string) {
    return "<a href=mailto:" + string + ">" + string + "</>";
}

3. Changed the size of the photos
In the tutorial, the photos are on the small size. I wanted them to be bigger. To learn how to do that, I went to the Random User API documentation and read how to get bigger photos. It was a simple change.

Random User API

See more about learning JSON by building a simple website.

Customize your command line interface in Mac OS X

When you use you the MacOS for a development environment, you will have to use a command line interface to get some things done. With MacOS, you get the default command line interface tool called Terminal. You may notice that the Terminal window is a bit bland. What can you do? You can customize it.

Customize Your Terminal Window in MacOSX
Photo By: joffi

When you use you the MacOS for a development environment, you will have to use a command line interface to get some things done. With MacOS, you get the default command line interface tool called Terminal. You may notice that the Terminal window is a bit bland. What can you do? You can customize it.

Customize Terminal

When you first open Terminal, it looks a bit like this.

terminal macosx

To make it look better, you’ll want to change the appearance by changing its colors. It comes with 10 different profiles or themes: Basic, Grass, Homebrew, Man Page, Novel, Ocean, Pro, Red Sands, Silver Aerogel and Solid Colors.

To pick a different profile:

  1. Open the Terminal
  2. Choose Preferences from the Terminal menu
  3. In the General tab, choose a new profile from New window with profile
  4. Close Terminal and relaunch

Not sure which profile to pick. You can open a terminal window with the selected profile. In Terminal, click on the Shell Menu, choose New Window, scroll over to the drop down menu and select a profile. A new window opens in the profile theme that you have chosen.

terminal window themes

You can also tweak a profile by changing fonts, colors and much more. Open the Terminal’s Preferences and click on Profiles. In the Profiles window, click on the + button to create a new profile. Then, change the settings as desired.

terminal profile window

After working with the Terminal window for a while, you may want to change how it looks. You can choose to change the fonts and colors, pick a theme or create your own. What if you don’t want to use the Terminal Preferences window, you can edit the .bash_profile file. Whether you customize by using the preference window or edit the bash file, you can make the Terminal window look the way you want.

How I make Atom work for me

My new favorite text editor is Atom Code Editor. With Atom, you can modify the editor to fit your needs. I am going to show you a handful of tips and tricks that I use to make Atom work for me.

How I make Atom work for me

Customize Atom

You can customize fonts, font size and themes.

Change font and size

Don’t like the default font? Is the size too small? You can change that.

Atom > Preferences > Editor

  1. Enter a font name that you want to use.
  2. Enter a font size.
  3. Save.

Atom Editor Settings

If you want to go a step further, you can edit Atom’s stylesheet.

Themes

Atom comes with two default themes: Light and dark. If you don’t like them, you can install a new theme. Don’t know which one to install. Use Atom’s theme search to find your next favorite theme.

Atom > Settings > Themes

Atom Themes

Keyboard Shortcuts

Want to work faster in Atom? Use these keyboard shortcuts. Since, I use Atom on my Mac, the shortcuts are for a Mac.

Duplicate a line

When you are writing code, sometimes you have to write the same line over and over again. Instead of copying and pasting, you can have Atom do the copying and pasting for you.

  1. Go to a line you want to duplicate.
  2. Press the keys CRTL + SHIFT + D. It copies and paste your current line.
  3. Repeat for as many times as needed.

Move lines up or down

Have you ever need to rearrange some lines? Move one up from its current spot. Instead of cutting and pasting, you can use this shortcut to move a line up or down one.

  1. Go to a line you want to move.
  2. Press CMD + CTRL + UP (arrow). It moves your line up one row.

If you want to move it down, use CMD + CTRL + Down (arrow).

Comment out code

Different code can use different syntax for comments. You can use a shortcut to comment out your code. It will put the right syntax for comments depending on the language. You don’t need to remember to use the right comment syntax.

  1. Highlight the code that you want to comment out.
  2. Press CMD + /. Atom add comments to your code.

Conclusion

Atom is a great text editor. I like that I can customize it to look they way I want by changing the settings or install optional plugins. Atom’s shortcuts help you to use it even more productively.

Finding photos for your programming posts

What options do you have for better photos on your programming posts? You have two options. Use a photo that you found on a free stock photo site or take your own.
Finding photos for your programming posts

Use a free stock photo site

You can find a variety of photos to use on your site. What free stock photo sites do I use?

What do you do if you can’t find a photo that works or need something specific? You have to make your own.

Make your own photos

With cameras on smart phones getting better and better, you can take your own photos. By taking your own photos, you can use them the way you want. You don’t have to be a photographer to take great photos for your blog.

Use screenshots

What is a screenshot? A picture of your screen with an app or browser window open. You can use a screenshot tool or your computer’s screen capture shortcuts. When you create a screenshot, you can show your entire desktop or a specific part of your screen. With graphic software like GIMP or Photoshop, you can add text to provide more details or highlight something specific.

Screenshot Bootstrap Template

Both stock photos and screen shots can help you to add personality to your post. Do you use both or only stock photos?