Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleSections
Section
level2
titleDescription

The description provides an overview over the question, usually defining the context. This makes the question shorter and allows it to be scanned quicker.

For simple questions, where the context is clear, the description is often overkill. Sometimes even the Short Description is more than is needed. But for complex environments, it may come handy. Check if the context may be transcluded from a Module document.

Section
level2
titleQuestion

Formulate the question from the reader's view, in the context defined in the Description. Try to make it short and precise. Readers scanning the questions should find it easy to locate the relevant documents.

Tip Box

Try to put the reader in the question. Refer to the reader with "I". This helps to take the right direction for formulating the question and makes it easier for readers to identify themselves with the questioner.

  • How can I ...?
  • What is the intended configuration for me to ...?
  • Where can I find ...?

But not all questions follow this pattern as in

  • What is ...?
  • What does ... stand for?
Section
level2
titleAnswer

Make the answer short and precise. Maybe add links for readers to find more information on this topic quickly.

Since questions and answers are usually aggregated on pages to form lists, it may make sense to add links to this section in addition to links in the References and Resources sections.

projectdoc-section
titleSubordinate FAQs

A list of FAQs that are closely related to this FAQ and therefore are attached as children to this document.

projectdoc-transclusion-macro
documentDocument Sections
idsstandard-sections-bottom

...