> Some thoughts on documentation: Complete, syntactically correct sentences that make sense. Paragraphs / sections that have a start and an ending. Clear, con

> Some thoughts on documentation: Complete, syntactically correct sentences that make sense. Paragraphs / sections that have a start and an ending. Clear, concise and consistent language (part of the "7 Cs of communication that actually works"). Documentation is not a poem-writing contest. Do not substitute pseudo-synonyms (e.g. table, relation, schema), that's inconsistent and confusing. Explain concepts and define key terms. A glossary tends to be immensely helpful, especially if it links back to detailled explanations of home-grown terms. And the usual basics, e.g. think about the intended audience (what can you expect them to know, what do they want, then give them that).