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

How do you reduce website bloat?

Why is my website slow? It is a common question developers, designers, bloggers and even your visitors ask. No website is immune from having speed issues.

How Do You Reduce Website Bloat
Photo by Farzad Nazifi on Unsplash

What causes website bloat?

How you designed and built the site affects its speed. Things like images, videos, CSS and code can impact your site. Even your server can affect how the site performs.

What can you do to speed up your site?

1. Optimize your images

You may be using images created in file formats that aren’t designed for the web. They may be large in file size as well. You can use an optimize tool to shrink the file size down without noticeable loss in quality. When you optimize an image, it loads faster on your site.

2. Get rid of unnecessary images

Check your web server for unused images. Unused images can affect user experience and performance of your site. If you aren’t using these images, delete them off your server. WordPress users can clean up their images using plugins or manually. If you have Windows, you can use Powershell to find and remove used images.

3. Optimize your videos and other files

Large files can slow a web site down. Files like videos or PDFs get quite large. You can optimize them before uploading. For PDFS, you can use Adobe Acrobot Pro’s PDF Optimizer to make them faster for the web. With videos, you can use a video hosting service like Vimeo or YouTube to host your videos. Then, you can embed them on your page.

4. Optimize your CSS

CSS files can get large and unruly after a while. Optimizing and managing them can be a challenge. It can be hard to find unused styles. You can use a tool like Helium CSS to find them. By getting rid of unused styles, you can reduce the size of your CSS.
Some of your styles are used more often than others. Print styles are used when a page is printed. You may want to separate them into their own file. With frequently used CSS, you may want to consider using inline styles instead. Before uploading your CSS, you can use a minifier to reduce the amount of whitespace it uses.

5. Check your code for speed issues

Are you using old code? If you are, you may need to rewrite, refactor or even replace it. Look at older code and decide if you need to keep it. If not, remove it.

6. Review the content of your page.

You may have too many items on your page. Do you have old or outdated content? If so, you can remove them. Review the rest of the items on the page to see if you can remove some content and still achieve the same goals of the page.

Summary

Preventing website bloat can be a full time job. By changing your development process to include optimization. You can prevent it from getting slow.

What can you do with FlexBox?

FlexBox is a flexible box layout model for the web. This model gives you a way to automatically rearrange responsive elements. They can adjust in size either increasing or decreasing depending on the device size. FlexBox can be a great addition to your CSS toolbox. It helps you to write adjustable and adaptive CSS.

What can you do with flexbox
Image by Magic Creative from Pixabay

How do I get started?

You can start by reading guides on how to use FlexBox. The Mozilla Developer Network has a guide on the Basic Concepts of Flexbox. Or try CSS-Tricks’ A guide to FlexBox.

If you need to fix a problem right away, you can use Solved By Flexbox to find a solution to common problems.

3 different ways to use it in your projects

1. Centering items on a page

Without FlexBox, it can be challenging to center items like text or images on a page. Sometimes, you have to resort to hacks to get it to look the way you want. FlexBox makes it so much easier. Use these tips to center items either horizontally or vertically.

2. Photogallery

You want to create a photo gallery that is responsive. Use this photo gallery to make one that looks like Flickr or Google Photos.

3. Responsive Tables

Tables are not responsive. You can make them be by using a little bit of FlexBox without having to redesign them.

Need more?

Flexbox Patterns has solutions to problems that you can use. It demonstrates the solution and shows you how to create the flexible box layout yourself.

Getting Started with CSS Variables

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.

How do you fix problems in print CSS?

A print stylesheet allows you to print a webpage. Testing a print stylesheet can be challenging. You create print styles to manage how the page prints, but it still doesn’t look right. What do you do when you need to fix or find a problem that occurs when the page is printed?

How Do You Fix Problems In Print CSS
Photo by Fernando Arcos from Pexels

You have two options use the Print Preview or the browser’s developer tools.

Print Preview lets you see how your web page looks on the printed page. You can see which elements to hide like navigation bars, footers or certain images. It also helps you to identify simple problems. Problems like large text, too much space between elements and extra styling that may use too much ink.

What do you do when you can’t find the source of a problem? Use your browser. Chrome, FireFox and Safari allow you to display print styles directly in your browser. This option is great for seeing how your design looks without print the page out. You can use the inspector to diagnose issues with your CSS. It can help you identify design issues that need a print style either created or modified.

For example, I had an app that printed a receipt. It printed on two pages instead of one. First, I used the Print Preview to find out what elements to hide when printed. After that, I saw that it was still printing on two pages. I couldn’t see what was causing the issue.

I changed the Developer Tools to show the print CSS. When I used this option to view the receipt with the print styles, I found the source of the problem. The problem was in the footer. I started to look at the styles for it. The footer had a height of 10.75 ems. I experimented by turning off the height. It changed from printing on one page instead of two. To fix this issue, I added a new print style for the footer and made the height auto. When I looked in print preview, it printed an one page.