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
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.
- Question & Answer
- Each question formatted with heading level 5, ===== Question here? ===== as below:
- Should be brief, approximately 1 sentence of about 12 to 25 words.
- They may be discovered by recent activity on #pcbsd especially but also from other sources such as social media, mailing lists, or forums.
- 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.
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 ====
- 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)
Small edit, large implications?
I replaced a broken external link shortcut: http://wiki.pcbsd.org/index.php?title=PC-BSD_FAQ&diff=81358&oldid=19222
The manner in which the link had been broken by a change in the target URL from https://www.freebsd.org/doc/books/handbook/linuxemu.html to https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/linuxemu.html leads me to think that other (perhaps many other) "fbsdh" citation template shortcuts may be similarly broken by the addition of "en_US.ISO8859-1/" in URLs at the FreeBSD site. If so, updating the targeting algorithm for the template shortcut seems desirable. --Kevjonesin (talk) 00:41, 8 July 2015 (PDT)