DesignWIKI

Fil Salustri's Design Site

Site Tools


wiki:document_mode

Document Mode

Document mode is both a style of topic structure, and a technique of writing those topics.

Problem: You need to record/communicate factual information or reference material.

Solution: Document mode is essentially the standard presentation of material one finds in books and articles, tweaked slightly for wikis.

Purposes:

  • Establishing a base to start a discussion (see discussion mode)
  • Summarizing discussions that are winding down or getting too disorganized (see refactor by summarising).
  • Reporting past events
  • Writing authoritative documents (e.g. roadmaps, mission statements, etc.)
  • Progress reports
  • Synthesizing information from disparate sources in a meaningful whole.
  • Etc.

Document mode topics are generally more easily understood by novice wiki users (they're not used for online discussions).

So, use Document mode.

  • Start the topic with a brief opening statement that captures the intent of the topic.
    • One convention is to start the topic with an indented block paragraph in emphasized text with a horizontal line below.
  • Be clear on whether you will maintain the accuracy and currency of the document.
    • A short note at the bottom of the topic is usually sufficient.
  • Document mode topics can start a discussion, so make sure there's room — usually at the bottom of a topic – for that discussion to start.
  • If the topic covered is particularly complicated, consider starting the topic with an overview for novices, then add the gory details further down (or even on a separate topic).

If you're converting a discussion mode topic to a document mode topic:

  • Make sure the original discussion topic remains available (possibly in a separate topic) to ensure that contributors can verify that the Document mode topic accurately represents their contributions to the discussion.
  • Change the 1st person singular to 1st or 3rd person plural.
  • Remove the in-line attributions and put them at the end under “Contributors:”.
    • It is understood that individual authors may not have chosen the exact words used; that we have a consensus and hence probably compromises.

But:

  • Remember that you may be the author of a document mode topic, but the content is generally assumed to “belong” to the user community.
  • Beware making unnecessary categorical statements (see wetiquette).
  • Make sure you can site references as appropriate.
  • You may implicitly become the owner of the document; i.e. others may assume you will maintain it. Be clear on this point, one way or the other, at the outset.
  • Discussions arising from a document mode topic should eventually be integrated back into the document mode topic.

See Also

wiki/document_mode.txt · Last modified: 2020.03.12 13:30 (external edit)