Difference between revisions of "Talk:PC-BSD FAQ"

From PC-BSD Wiki
Jump to: navigation, search
(Guideline)
 
Line 1: Line 1:
In addition to the acknowledgement on the main page about how it needs work, the following guideline specifies a radical overhaul of the current [[PC-BSD FAQ]] page.
+
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 ==
 
== PC-BSD FAQ: Guideline ==
 
=== Explanation ===
 
=== Explanation ===

Latest revision as of 15:16, 26 July 2012

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

[edit] PC-BSD FAQ: Guideline

[edit] 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.

[edit] Format

Question & Answer
Each question formatted with heading level 5, ===== Question here? ===== as below:
[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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)