Thoughts on programming, web development and design.

Circuit Board

Category: Miscellaneous Page 2 of 9

Miscellaneous

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.

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

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?

Create a site-specific plugin for your WordPress site

As you develop your WordPress website, you need to add additional functionality. How do you add it? You can write custom code that you add to your theme in the functions.php or create a custom site-specific plugin.

Create a Site-Specific Plugin For Your WordPress Website

Both options allow you to add the code to WordPress. Where you choose to add the code affects how it functions.

Theme or Site-specific plugin?

Is the code you are going to add specific to how the theme or do you want it to work even when you decide to switch themes? If the enhances to your theme, you want to add your code to the functions.php. This code only works when you are using this theme. If this code needs to work no matter what theme you have installed, than you need to create a site-specific plugin.

What type of code do you add to a site-specific plugin?

  • Widgets
  • Shortcodes
  • Custom post types
  • Custom code snippets

Steps to create the plugin

The steps for creating a site-specific plugin are the same for any plugin.

  1. Create a new folder for your plugin. Use the format of yourwebsitename-plugin.
  2. Create a new file. Use the name of yourwebsitename-plugin.php.

<?php
/*
Plugin Name: Site Plugin for yourwebsite.com
Description: Site specific code changes for yourwebsite.com
*/
/* Start Adding Functions Below this Line */


/* Stop Adding Functions Below this Line */
?>

  1. Add your code to your plugin file.
  2. Upload code including the folder to your website.
  3. Activate and test.

 

With your site-specific plugin, you can add new features or functionality to your website by adding the code to your plugin. By adding the code to your plugin, you keep your code separate from your theme. When you need to add a new code snippet or upgrade your theme or WordPress, you won’t break your website.

Related Post

Page 2 of 9

Powered by WordPress & Theme by Anders Norén