Why Write Technical Documentation

As a developer, you spend a lot of time writing. More than writing code. You reply to emails, update bug requests and write project documentation and more. Code allows us to communicate with computers. With people, we need to use words to communicate.

Why Write Technical Documentation
Image by ha11ok from Pixabay

Every day, we communicate with clients, users, team members and other developers. We write all kinds of different things to communicate with them. From a quick email to help them get started using our product to a full user’s guide.

"If you can’t automate it, document it. – Hila Fish

Why write?

You want to write technical documentation to help reduce your work load. Technical docs help you to remember why you are doing things a certain way. You or future developers will be glad you took the time to document the choices made.

Documentation keeps your project on track

When you work on your own projects, writing becomes more important. You write documentation to help explain what your product does. How it solves your customers’ problem and how they can use it. If you like to work on many projects, documentation helps you to keep going. Simon Willison explains how to use documentation to maintain multiple projects.

Document your project quirks

Every project has its own quirks. You make choices that affect how things turn out. To help your future self or the next developer, document the following:

  • Choices that you make while you are working on the project
  • Things that bugged you
  • Items that aren’t clear or straight forward
  • Any surprises that came along
  • Issues or things to consider when using this tool or language feature

Read more about writing better documentation

Making an Advice Generator

Have you tried a coding challenge? Coding challenges allow you to stretch you programming and design skills. You have your choice of places to find coding challenges.

Making an Advice Generator
Image by Dean Moriarty from Pixabay

You can pick coding challenges that ask you to build components or a simple app. Some of the challenges include working with an API.

Advice Generator

The Advice Generator coding challenge on Frontend Mentor has you working with an API. This API provides you with data for displaying advice on a web page.

Screenshot of Advice Generator with Advice #100: Everybody makes mistakes.

How I Built It

I created this app using HTML, CSS and JavaScript. For CSS, I started with Bootstrap to help structure the design. Then, I used FlexBox to manage the layout.

Fetching Data

I used the JavaScript Fetch API to fetch the data from the Advice Slip JSON API and display it on a web page. By default, it picks a piece of advice and displays it. If you want to get another piece of advice, you need to click the dice icon. This icon button retrieves a random piece of advice.

If you don’t use the cache option of no-cache, you get the small piece of advice. When you call the API which returns a random piece of advice, it doesn’t display on the web page. It is caching the data. When you use the no-cache option, fetch retrieves a random piece of advice.

Design Challenges

The layout required centering the advice box and the dice icon for the button. To handle this, I used FlexBox to center the box and to align the button on top of the bottom of the box. You need to use a combination of absolute positioning and FlexBox to get the dice to appear where you want it.

The advice box needs to be flexible. It has to expand and contract depending on the size of the advice. FlexBox makes this easier.

Other Coding Challenges

Resilient Web Tips

Whether you use a computer, phone, table or some other device to access the Internet, you expect it to work. Sometimes things can break. Your connection is slow. Images don’t load. They are using a third-party tool that is having their own issues with the Internet. What can you do? Wait. Try again. Come back later to see if they fixed it.

Resilient Web Tips
Image by 3D Animation Production Company from Pixabay

The Internet provides information to users. By allowing them to use, whatever tools they wish. This feature makes the web resilient or fault tolerant.

What is a resilient website?

Being fault tolerant or resilient is part of the how the web works. HTML and CSS are the simplest tools for building a website. If errors are in either the HTML or CSS, the browser skips the errors and loads the page anyway. It may not look the way you want, but people can read the information.

Other programming tools like JavaScript don’t have built in fault or error tolerance. To make your code more resilient, you have to handle errors and missing information.

What can you do?

1. Start with the basics

Use HTML and CSS. HTML is the foundation of the web. You can build a website with HTML only and have it work. CSS allows you to use new features and older browsers ignore what they don’t understand. The more things we add to our web apps, the more they affect user experience. site performance and accessibility.

2. Pick the right framework for the job

JavaScript can enhance the user experience. It can also slow the site performance down. JavaScript Frameworks allow you to build things that you can’t using HTML and CSS. Before you decide to use a framework, you need to ask if you really need it. Or can you use Vanilla JavaScript instead? Consider adding less to your next project.

3. Prevent errors and make them easy to fix

Lot of things can break on the web. Your network connection fails. You clicked on the wrong thing. Or something else breaks behind the scenes. Web developers can build their web apps to prevent errors and make them easy for the user to fix. When you use JavaScript, you need strategies for making a resilient UI. Callum Hart shows you how to build a resilient JavaScript UI.

Where can I learn more about making resilient websites?

Jeremy Keith wrote Resilient Web Design. A book that gives you ideas and approaches on how to build a more resilient web.

Getting Started with JavaScript Accessibility

Accessibility means making your content as available to as many people as possible. You don’t know who visits your content. What browsers they use or how fast their internet connection is. You can build an accessible website with JavaScript You need to keep these considerations in mind.

Getting Started with JavaScript Accessibility
Image by Daniel Agrelo from Pixabay

JavaScript can be necessary

Sometimes, a no JavaScript solution may work. Other times, you may find that JavaScript helps to improve accessibility. It depends on what you want to do. Sara Soueidan wrote about her experience with building a tooltip without JavaScript. She found that it was harder than she thought.

Many people use a keyboard to surf the web. To navigate by keyboard, you jump from one focusable element to the next. You can start by using the tab key to move from one element to the next.

Which elements are focusable? HTML has interactive elements with built in focusability. Elements like text fields, buttons and select lists. You can navigate them by keyboard automatically.

Sometimes, we use HTML elements like <p>, <h2> or <div> to create custom interactive components. If you don’t make these elements focusable, this creates problems for keyboard users. The tab index attribute solves this problem by making a non-focusable element focusable.

Use the right amount of JavaScript

The problem starts when you rely on too much JavaScript. HTML and CSS can do a lot of things that you used to need JavaScript for. Now, you can use HTML to build your content and supplement with JavaScript.

Use the <button> tag to create buttons. You can use <div> or <span> tags to recreate the functionality of a button. When you choose to do this, you have to write extra code to mimic the behavior of a button. It is easier to use the button tag when you need a button.

Want to know more?

Use the Accessibility Developer Guide for best practices on creating accessible websites. Or JavaScript Accessibility Best Practices.

Image by Daniel Agrelo from Pixabay

Getting Started With Web Components

Everyone has their favorite tools, languages and JavaScript frameworks. JavaScript frameworks allow you to create components. Which you can reuse throughout your apps. What if you can’t use a specific framework? You can use Vanilla JavaScript to build web components.

Geting Started With Web Components
Photo by Pixabay from Pexels

What are web components?

Web components are a set of web technologies that allow you to create custom reusable HTML elements. These elements are not dependent on using a specific framework. You can use them without having to load a framework like React or Angular.

To build a web component, you can use these three technologies:

  • Custom Elements: A JavaScript API that allows you to create custom elements which you can use like HTML tags.
  • Shadow DOM: The Shadow DOM API provides a way to attach a hidden and separate Document Object Model to a web component. This keeps your component’s HTML, CSS and JavaScript separate from the rest of the web page.
  • HTML Templates: Use HTML tags <template> and <slot> to hold HTML that doesn’t display when the page loads. You load it with JavaScript at a later time.

Can I use web components in a JavaScript framework?

Yes. You can use your component in whatever JavaScript framework you want or none at all. If you need to switch to a new framework, you don’t have to rewrite your web component. Learn how to get started with building a web components.

Want to create your own components?

Check out these tools and resources for building your own web components.

Want to learn more?

You can learn more from the Web Components Community and Web Components.