Benefits of a proper Document

Clear statements, clean words and well-organized structure are most important factors when writing a document. They make a good impression on readers and can help author captures the heart of audience. People tend to read more when they are at ease. Therefore, a clean, short, well-stated document are often welcomed. For instance, take a glance at Stripe document and you will see the different.

Stripe Payment Guide - Quick Start

There are advantages which can be analyzed from their document structure:

  1. Documents are developer guidance:  Stripe documents are either tutorials or guidelines. Stripe provides a guide for developer as well as answers what developers seek. Stripe is known for thoughtful documents.
  2. Documents are clean & clear: Stripe documents are easy to read due to their simplicity and tidiness. Keywords and titles are also distributed wisely. For those said factors, developers can quickly navigate through contents, thus they find what they seek with ease.
  3. Statement comes with demonstration: Stripe construct developer-oriented document, delivering attractive and interactive examples to their customers. As "study goes as a pair with practice", Stripe does it well.

Stripe organizes documents so well that developer users feel right at home. It is not a surprise that Stripe got high rating and reputation from developer community.

It is important to understand the values of a well-organized document. Your thoughtful document can go a long way while attract lots of impression.

How to create a proper Document

Language

In writing, it is essential that language should be used with care

  • Write in English.
  • Use simple and common words. The document should be clear and easy to understand.
  • Write in the 3rd person (use “we”, “you”, “us”, “one”, instead of “I” or “me”).
  • Be clear, concise, and stick to the goal of the document.

Type of document

Before writing, author should have a clear vision of his/her document role. Although there are several type of documents, the most common types are tutorial and how-to guide. They are often mistaken because of similarity; they can still be distinguished.

TUTORIALS

A tutorial:

  • is learning-oriented
  • allows the newcomer to get started
  • is a lesson
Stripe Payment form creation Tutorial

HOW-TO GUIDES

A how-to guide:

  • is goal-oriented
  • shows how to solve a specific problem
  • is a series of steps
Digital Ocean - How-to guide to create a Cluster

Either tutorial or guide, writer should always put the statement or result on top of their document. It would make the document purpose clear, thus more visible to readers.

Document Content

These guidelines help toward the goal of having every user’s search of documentation yield a useful result, and ensuring content is helpful and easy to consume.

What to include:

  • Helpful information, processes, and tips for implementing, using Uiza features. Any content types/sources, if relevant to Uiza features. You can freely include presentations, videos, UI coding pluggin, etc. If you get an outside source, remember to rephrase or summarize, put a link and credit to that outside source. For example: (*) Picture Credited to https://www.rheinmetall-tp.com/
  • Link document from the higher-level index page and other related pages.
  • Do not duplicate information.
  • Structure content in alphabetical order in tables, lists, etc.

Punctuation

Check specific punctuation rules for Uiza document below.

List items

  • Start list items with a capital letter.
  • Always leave a blank line before and after a list.
  • If you describe a sequence of steps to follow, make sure that you use ordered lists.

Make your document work

Overall, these are standards to create a proper document. For the moment, we hope it becomes much clearer of what to write, how to write it and where to put it. We will continue to update changes to keep up with top notch SaaS document template.
(*) Banner picture Credited to https://www.rheinmetall-tp.com/

Credit to: Daniel (daniel@uiza.io)