Talk:PC-BSD FAQ

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.

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)

---