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

Image source: PSPDF

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 styleguides 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.

Setting up Docz

First step: Initialize the npm

npm init -y

npm init

Second step: Install the docz package

npm install --save-docz docz

npm install docz

After installing the Docz package in your project, you may have to install react and react-dom as well and after that, add three scripts to your package.json to run, build and serve your Docz website.

\

{
  "name": "aviyel-docz-demo",
  "version": "1.0.0",
  "scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build",
    "docz:serve": "docz build && docz serve"
  },
  "dependencies": {
    "docz": "latest",
    "react": "16.8.0",
    "react-dom": "16.8.0"
  }
}

Docz uses the MDX format that allows you to easily integrate JSX inside your markdown files.

Spin up the script by simply typing:

yarn docz:dev

or

npm run docz:dev

Third step: create an MDX file.

There is no need to follow any file architecture or convention. You can just create your .mdx files and put them anywhere inside your project.

Let’s create and index.mdxcopy the script below and then put it inside wherever you want.

index.mdx

---
name: Awesome Documnetation
route: /
---

# Hello There

Creating an awesome documentation using DOCZ

Again,spin up the script by simply typing:

yarn docz:dev

or

npm run docz:dev

You can now open the browser and visit localhost:3000 to see something like this:

documentation using docz

What Points to Avoid While Writing Front-End Documentation?

Don't promise - When creating documentation it is advised not to promise future features. Only include features that already exist in the product or the ones that will be completed before the document is officially published.
Do not duplicate - If you have described several similar algorithms/designs/Apis etc., do not duplicate all this all over again. Have it described in one place, and use reference in other sections.
Unsupported features - documenting on unsupported features should be excluded, nobody is interested in the testing units you had to conduct before launching your product. But if it is necessary be sure to explain the support status and give more details about the same.

Wrapping Up

Concise documentation helps engineering/developers to focus on delivering value to their customers. These key points should be considered in the process of producing software documentation. Good software documentation should be provided whether it is a specifications doc for programmers and testers or software manuals for end-users. Comprehensive software documentation is specific, concise, and straight to point.

As mentioned above, it’s considered good practice to produce good documentation for our product users as described in this article. To ensure developers out there don’t stop writing precise and inspiring docs, Aviyel is teaming up with open source projects to develop knowledge-based repositories with fellow creators, writers and project maintainers. You can follow Aviyel’s discussion here.

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

Hillary

Ankur Golwa

RamKumarRAviyel

Vanshika Srivastava

Joshua Poddoku

UtkarshPandey 0

Charu Veluthoor

RusselAviyel

PetrinaPintoAviyel