Structure
The Wiki
Articles for users belong to the Learn space.
Spaces and Subspaces
For software project documentation, see additional guidelines.
Each Wiki's space and subspace has its own table of contents. Always include a welcoming page that would also serve as the landing page of the space. Briefly explain what kind of information the reader could find there and briefly mention points of interest like getting started articles, contribution guidelines, or API reference.
Group related articles in categories or subcategories. Arrange the whole space in a natural order of learning. Rearrange articles if an article refers to a subject that is introduced down the table of contents.
Anticipate that someone could read the wiki out of order and link related subjects.
Articles
Structure an article just like you would organize a space: explain basics first and advanced topics later, and group paragraphs with sections and subsections if they share the same topic or theme.
See the formatting recommendations on headings.
Paragraphs
Each paragraph should convey only one thought. If a paragraph has multiple ideas, split it. If multiple paragraphs convey the exact same thought, try to remove duplicates or merge them.
The reader should understand what a paragraph is about from its first sentence. Sometimes readers just skim over the article to quickly find a single bit of information — and your article should respect that. It also detaches a new paragraph from a previous thought and provides you with context to naturally elaborate on.
The first sentence of the first paragraph convinces the reader to start reading. Never spend it on weak statements like "This is the opening article in a series on the Topic, and it explains such basics as this and that." The best introductions are concrete.
Miscellaneous
Sometimes information is best served with supporting media — see the formatting recommendations on freestanding elements.
Parallel structures help with reading and navigation. It works on any level from space to sentence. Install, Configure, Run sounds natural, and Install, Initial Setup, Run does not. Sometimes your prompt would do better without a parallel structure: for example, a paragraph where every sentence starts with the same phrase or word could sound repetitive.