Author: admin

Write Better Documentation for Your Code

Posted on by admin

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

Getting Started with CSS Variables

Posted on by admin

What are CSS Variables?

Most programming languages allow you to use variables. Variables are used to store information and manipulated by the program. In CSS, you previously need a preprocessor like SASS or LESS to use variables. CSS Variables are custom properties that you define with specific values and reuse throughout your CSS document.

Getting Started with CSS Variables
Photo by Pexels from Pixabay

In CSS as well as programming languages, you can declare your variables either globally or locally. A global variable is a custom property that is available to your entire HTML document. To declare a global custom property, you use the :root pseudo-class.

For example, you want to define your theme colors. You can use the :root pseudo-class to do that.


:root {
    --main-color: blue;
    --main-text-color: aqua;
}

You can also declare a variable locally. By declaring a custom property locally, you limit the scope or impact that the variable can have.


.primary-background-color {
    --background-color: teal;
}

When you create a CSS Variable, you can overwrite the value. By taking advantage of cascade, you can create a new style that changes the default value of a global declare variable.


.text-color {
    --main-text-color: orange;
}

Var()

Preprocessors allow you to use a variable by referencing its name. You use the Var() function when inserting the value of a custom property.


.featured-content-box {
    background-color: var(--main-color)
}

Calc()

Sometimes you need to do a little math to get your styles to work they way you want them to. Calc() is a native CSS way to do simple math calculations. With it, you can do addition, subtraction, multiplication and division. CSS Tricks talks about use cases for Calc().

For example, you may want to change the width of a style.


.box {
    width: calc(100% - 80px);
}

Why use?

CSS Variables can be overwritten, cascade down and used in JavaScript. If you don’t want to use a preprocessor like SASS or LESS, you can use custom variables to make managing your styles a lot simpler.

In Web Dev Simplified’s CSS Variables Tutorial, he gives you a quick introduction on how to use them. You learn what they are, how to write them and use them with JavaScript.

Summary

At first, CSS Variables sounds complicated. They can help you to make your CSS easier to maintain. Variables are a lot easier to use than hex or hsl codes.

Build Code With Accessibility

Posted on by admin

What is accessibility in web development? It means building websites that as many people as possible can use. Accessibility benefits everyone not only people with special needs. Have you tried to use your phone in outside in the side or with one hand? You may have given up or waited until later to do what you needed. If you have special needs, using an app or website can be a challenge. Accessibility means developing websites that people can use regardless of their physical and cognitive abilities. Or how they access your website.

Build Code With Accessibility
Photo by Zan Ilic on Unsplash

How do you build software with accessibility in mind?

In her talk at Dot Net Conference 2019, Rachel Appel explained how developers can build accessible websites without greatly changing how they code. People have variety of needs. When you develop, you need to make your code usable for people with a wide range of visual, cognitive, hearing and motor abilities.

Visual

People with visual issues include low vision, blindness and color contrast. Some people may use a screen narrator to help them navigate your website. For people using a screen narrator, use skip links. Skip links allow them to skip over the navigation and go directly to the content.

For making sure that your site is readable by as many people as possible, you can use Color Oracle, a free color blindness simulator. It is available for MacOS, Linux and Windows. You can also use Accessible Colors or WebAim’s Color Contrast Checker to ensure check your color choices.

Cognitive

People with cognitive difficulties includes learning and age-related issues. You want to keep things simple and clear. Write using short sentences, active voice and simple words. Use headings and labels to help people easily find information. See Mozilla’s Cognitive Accessibility for more tips.

Hearing

People have a wide range of hearing abilities. With videos or audio, you want to include transcripts and close captioning. In your software, don’t rely on sounds alone for feedback.

Motor

People with motor issues can have tremors, difficulty moving a mouse and more. Avoid pop-ups if you can. When you can’t, make sure that they can be closed easily. Use alt tags on all images that are not decorative.

By developing for a wide range of people, you make sure that your website is usable no matter how or where they access the web.

Read more

Should you build a website with a static site generator?

Posted on by admin

How do you build a website? For most developers, there were only two options to choose from. You create a website by hand coding every single page in HTML, CSS and JavaScript. Or you use a content management system like WordPress. Now, you have a third option. You can use a static site generator.

Static Site Generators

What is a static site generator?

Static websites don’t require a database. Each page displays images, videos and text. They don’t pull information from a database when you go to the page or do something on the page. You can build a static website using a text editor. A static site generator helps you to build a website quickly. It creates all of the html code for each web page. A generator lets you focus on the important part, the content, not the structure of a web page. One of the popular generators, Jekyll, lets you create websites and blogs.

Why would you want to use a static site generator?

  • Pages built in HTML load faster. They don’t have to make calls to a database in order to display a page.
  • You can control how the website looks. When you use a Content Management System (CMS), you must build your website the way the CMS wants.
  • Your website is too small for a CMS. For some projects, a CMS can be overkill. You wanted a site with 5 pages that lets people know about your business. A CMS has features that aren’t needed by this website.
  • CMS’s require continual maintenance. Your CMS may make changes to improve functionality and security. Any themes or plugins that you use may have additional updates that will need to be monitored and updated as needed.
  • Better Security. A CMS has a database, a login and other code that opens the site for attack. This can make it harder to find problems. You may have to start over by deleting everything including the database. With a static site, attackers have little or no opportunities to damage your site. They would need to gain access to your web host to damage your pages or upload malware. When that happens, you can change your password, delete the site and re-upload it again.

Why you should use a CMS instead of a static site generator?

  • Your website has a large number of pages to maintain. A CMS makes updating and changing a website quick and easy.
  • No administration. You have to know markup and generator tools in order to make a simple change.
  • Limited themes or other resources available. If you want to do something like moderate comments, you have a limited number of options. With a CMS, you can choose from readily available plugins or themes to do what you need.
  • Your client wants to update their website themselves. Static site generators currently lack an administration interface to make this easy.
  • You can’t decide which static site generator to use. With a CMS, you choose one of the popular ones: WordPress, Drupal, Joomla or Kentico. Static Site Generators come in many different flavors. You have to decide what programming language it is written, what kind of website you are creating and more in order to narrow you selection down.

How do I choose a static site generator?

You’ve decided that a static site generator is a good solution for your project. With many static site generators to choose from, which one do you chose? First, Use staticgen.com to review the Top Open-Source Static Site Generators. It allows you to sort by languages, stars, issues, forks and name.

Then, ask yourself the following questions to narrow your choices down:

  • What type of site are you going to make? Some static site generators work better for a blog.
  • What programming languages are you familiar with? You can choose from JavaScript, Ruby, Python, Go, PHP and more.
  • What templates does it use? Liquid, EJS, or Jade.
  • What type of license? MIT, BSD, or APL 2.0
  • How many people use this generator? The more popular it is, the more likely you can get help when you need it.

Summary

Is your next web project going to be built with a static site generator? A static site generator can help build a fast and functional website without the extras that a CMS needs. Static Site Generators as well as CMS’s have strengths and weaknesses that affect the design of your website. As with any web project, the type of tools you choose should work with the content you intend to put on the website and not against it.

What to learn more?

Mobile Design Typography

Posted on by admin

Content is the most important element of your website. With a wide range of mobile devices available to people, your websites and apps must be readable on all. To maintain the readability of your content, you need to consider the fonts you choose, size, contrast and line length. How do you use Mobile Design Typography to make your content responsive and readable?

Mobile Design Typography

Fonts

Not all fonts look good on a small screen. Display fonts like script fonts may look good on a desktop screen, but on mobile they can shrink down too small to read. A script font like League Font is fine for the desktop, but on mobile it can be unreadable.

League Font

What are your options?
You could increase the size of the font. At a larger size, your chosen font may be look better. Or you could replace the font with one that is readable on small devices. You have to decide if you really need to use this font in your design.

Size

Size is also important. Too small and your content is unreadable. People leave sites if they can’t read it on mobile. If you choose a size that it too large, it could dominate the content. It could take up so much space that you end up scrolling constantly while reading the page. You have to find a size that works well at that size.

Line Length

How long should a single line of text be? It depends. Readability is determined by the font, character and word spacing and the word lengths. Even the device that you are using can affect readability. A general guideline is 9 – 12 words per line. 9 – 12 words is a comfortable range for people to read. Line Length and Column Widths explains why your text should be about 9 -12 words long.

Contrast

What is contrast? Contrast is how every element in a design which includes font, size, color, line length and images works to create a good user experience. The easiest to learn is color. How do your color choices affect the design? With mobile design, you need to also think about size, font, line length, position and shapes. On Web Designer Depot, John O’Nolan explains how to fully understand contrast in design. He shows you how to use them for a better user experience.

Horizon Coworking in Madison, WI

Summary

Your content is an important element of your design, especially on mobile. When developing for mobile, consider how the font type, size, line length and contrast can effect the readability of your site. If it isn’t readable, your visitors will leave. Keep them on your site by focusing on how fonts look on mobile.

For more information on Mobile Typography, check out these articles: