Talk:PC-BSD FAQ

From PC-BSD Wiki
Jump to: navigation, search

The following guideline specifies a radical overhaul of the current PC-BSD FAQ page, which of course means a lot of effort and time will be needed to truly convert it into a functional masterpiece.

Contents

PC-BSD FAQ: Guideline

Explanation

The primary consideration is that a FAQ is NOT a replacement for the handbook. A FAQ is most useful as a quick reference of short answers to common (and of course often repeated) questions. Therefore, a reasonable balance of brevity and utility must be formed.

Format

Question & Answer
Each question formatted with heading level 5, ===== Question here? ===== as below:
Question here?
Answer indented below the question. The question being a heading level will allow it to be visible within the automatic generated page contents.
Example: An example if given, indented once more and identified by Example: in bold.

Questions

Size
Should be brief, approximately 1 sentence of about 12 to 25 words.
Content
They may be discovered by recent activity on #pcbsd especially but also from other sources such as social media, mailing lists, or forums.

Answers

Size
Brief answers sufficiently thorough without being too verbose: At least one short sentence, up to a total of 8 sentences, or 100 words but not larger.
  • Answers may get revised to be more concise and to focus more directly on the question.
Use of links
No answer solely a 'redirect' to the handbook page, nor simply yes or no. A brief explanation should follow along with a link to further explanation in the handbook as needed, or a link to a more explanatory FAQ answer.

Organization

Rather than finding questions to fit an outline, the questions shall help to determine the outline. Built bottom-up. This may mean more work to keep organized due to likely topic section shuffling, but this also reinforces scrutiny of the FAQ as a whole.

Micro Topics
Used where at least 3 questions have something in common.
Added using level 4 header: ==== Question theme ====
Topics
Where at least 2 micro topics have something in common.
Added using level 3 header: === Micro Topic theme ===
Macro Topics
Where at least 2 topics have something in common.
Added using level 2 header: == Topic theme ==
  • Should any topic or micro topic grow or have need to become a substantial size, the content shall be placed in the handbook while a shorter and much more concise question and answer may remain in the FAQ.
  • Questions may come and go in relation to their pertinence. (ie. a problem that no longer exists in the current revision, or a question about how to install something that is no longer supported)