Available translations
loading results
General Notions on Documenting
Summary: The main challenge in producing collaborative documentation is in maintaining quality and consistency. Let's start with a few general guidelines that will help us set the tone for what's to come.
Foundations->Concept->Reusable Documenting Snippets->The Quest for Quality
The Quest for Quality
At Superalgos, we take pride in the quality of the product we are building. Documentation and tutorials are crucial parts of Superalgos.
That said, we understand that it takes time and effort to get to a quality product, thus iterating on early prototypes and implementing early-stage feedback is a good way to achieve the desired quality standards.
Tip: When you write documentation or build a tutorial for Superalgos, you become the maintainer of what you've created. It is your responsibility to keep the material up to date with the system, and to implement the feedback users may share! Your material must become the ultimate resource to learn the topics it covers.
Foundations->Concept->Reusable Documenting Snippets->Proper English
Proper English
There are at least two reasons why it's desirable to have spell and grammar-checked content:
- Proper language speaks to the quality of the product.
- Users who don't speak English may be using online translators, which perform well only when they have a proper source.
Important: Always use a grammar and spell-checker to make sure your content is as correct as it may be!
Foundations->Concept->Reusable Documenting Snippets->Use Precise Language
Use Precise Language
The ultimate goal of documentation and tutorials is to provide users with a hands-on learning experience covering topics in detail. In general terms, we know the material is good — or has reached a mature state — when users ask no questions about it in the Support Group.
Be precise and unequivocal with language. Read your writing over and over in search of phrases that may not be easily understood, or that may be interpreted in different ways. Improve the sentences to make them as clear as possible. Remember, the less clear your writing is, the more questions we have in the Support Group.
Tip: Be prepared to iterate over and over until the material stabilizes. That will happen when there are no more questions about the topic in the Support Group!
Beauty and Readability
The ultimate goal of the Docs is to provide the tools that enable everyone to become power users as soon as possible. Beyond clear and accessible content, the Docs must also be easy to read.
Long pages of plain text are quite painful to read… and are ugly! Instead, alternating different kinds of paragraph styles help make pages nicer and easier to read. Use the callout style for paragraphs that offer key insights or revelations that make up the core of the topic in discussion.
Foundations->Concept->Reusable Documenting Snippets->Alternating Colors
Alternating Colors
Colorful pages look great, while white pages full of text are harder to follow. Make sure you break the monotony with the four different styles of boxes:
Tip: This is great for additional tips.
Note: Use this every once in a while to break up otherwise large sections of plain text.
Important: Leave this box for the truly important stuff. Things you don't want users to overlook or forget.
Warning: And this one, save it for real warnings. Things that may represent a threat or risk.
Foundations->Concept->Reusable Documenting Snippets->Title Case
Title Case
Always use proper title case for titles. But, what exactly is proper title case? Let's agree to the standard proposed on this blog post:
Tip: Titles look best when they span a single line. Use two-line titles only if strictly necessary!
Foundations->Concept->Reusable Documenting Snippets->Tooltips
Tooltips
The system recognizes the name of all entities that have a Docs Page when the name of the entity is written in title case. When that happens, the system automatically creates a tooltip for the phrase. This is a valuable resource, as it provides context that you don't need to explain.
Make sure you use this resource wisely, as too many tooltips on a single page may be overwhelming, and probably irrelevant.
Tip: When you believe the tooltip is relevant, then write the name of the entity in title case. If the tooltip is not relevant, then write the name of the entity in lower case.