The Do's and Don'ts of Front-End Documentation

Full article available on Aviyel for free

One thing almost all developers might all agree on is even if you have the best programming project ready for the world but, if it doesn’t have good documentation, chances are it won't reach the right audience. For instance, in an organization, a good set of well-explained rules could save you from having to repeatedly answer the same questions. The rules ensure that people can figure out how things work around the organization if key employees decide to leave the company. The same thing happens in a project, a well-documented guideline will help bring consistency and exposure to source code and ensures regular modification even if senior employees might want to walk out.

In the software technical industry, it can be really challenging for engineers to obtain documentation from product owners that can actually be used to build and test a product. This is because the chances of product owners being developers is very low, so they have very little concept of what information a developer needs in order to actually compose a functional digital product. This means that this task often falls in the hands of developers and technical engineers to maintain a library of documentation for the products they’re building.

Now, to help you get started with writing good documentation for your products here are some tips that might help you to curate full-fledged, quality documentation that can be used as both a tool for building a product and a reference for learning and testing your recently created product.

Enjoy!

What are the Types of Documentation Available?

We will agree that good, front-end documentation is important to the success of software products, and yet very few projects actually have good documentation. It's funny how even successful projects often have barely adequate documentation. You can resolve these issues by understanding the mechanism behind doc maintenance and by choosing the right one to document your product. The two main types of documentation include:

• Product documentation

• Process documentation

Structuring documentation into these categories helps ensure that each detail is covered and makes it easier to write and maintain. Our main focus in this article will be on the product documentation where we will cover what should be done and what should be avoided when writing the documentation, with these tips you will be able to make your software projects and teams more successful.

The Dos of Front-end Documentation

• Target Audience - Before you begin writing your documentation it is highly advised to define your target audience, the tone, style, and technicality you will use, depends on the audience you will be targeting.

• Understand the product - If you want to write great documentation, the first step is for you to be sure you understand how the products work. If you don’t even know how something is supposed to work, you can’t have much confidence that it’s working correctly. Plus, it creates uncertainty amongst teams about the working of a project.

• Structure and Markup - Structure your documentation by tasks relevant to the user instead of providing reference documentation by describing each part of the user interfaces individually. Always describe what a product can do rather than its limitations. You can follow these components to standardize your doc:
  Title
  Abstract
  Table of content
  Chapters
  Sections
  Contributors

• Use of visual aids - Provide diagrams or other graphic materials to help understand and communicate the structure and design principles.

• Keep it up-to-date - Documentation is only as valuable as it is accurate, so it's important to keep it updated with changes made to the UI and backend services. It is a good practice to make updating the documentation a part of the process.

• Language - We all come from different zones and we all speak different languages, this does not mean you need to translate your code into vernaculars. Writing your documentation in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn't familiar with English.

• Provide the definition of used terms and full forms of abbreviation - consider creating a reference page with all definitions, commonly used words, etc.

More Tips to Remember

• Define the purpose of the project in the documentation

• Document the technologies used

• Document any unexpected events that may occur

• Address how it will be distributed for public use

• Mention the expected, emphasize the unique

• Remember to backup

Where Can I Create Documentation of My Project?

The market is filled with really popular style guides and documentation tool to code your projects. However, I am a big fan of open source and prefer them only for my documentation needs. I mostly use Docz to curate technical documentation of my codes.

Why I Use Docz For my Front-End Needs?

While I prefer Docz for curating frontend documentation, you might also try VuePress if you have adopted Vue framework. GitBook could be your go-to option if you want to switch to a paid option. Plus, here's a catch. Open-source teams can use GitBook for free. However, I prefer Docz because:

• It’s Gatsby Powered

• Easily customizable

• Blazingly fast

• Based on MDX

• TypeScript support

It makes sure that your content includes all SEO requisites, making it more user-friendly and readable.

Still in the Article...

Now we have a few easy steps still left out.
They include:

• A guide on how to set up Docz
• What Points to Avoid While Writing Front-End Documentation?

Check out the complete Article on Aviyel and also follow discussion to get all the required details.

☕ Help me Get a Cup of Tea

Connect With me at Twitter | Insta | YouTube | LinkedIn | GitHub

Enjoy Coding ❤