サイト構築のヒント

良いWikiページを作成するためのヒントです。自由に追加したり、コメントをつけてください。

• ページの最初は、第一見出しで始めます。タイトルは意味のあるものを。
• 文章のまとまりを段落として、空の行で離します。平均的な段落は、10から20行を超えないようにしましょう。
• もし、段落が3から5を超えるようであれば、見出しをつけて、セクションに分けましょう。
• ページの全体をみるのに2〜3回以上スクロールするようであれば、最初の見出しの後にページの項目の短い概要を入れてください。
• もし、他のWikiのページへのリンクや外部リソースが多ければ、参照のセクションを追加してください。

• 単語や短い文章を強調するには、太字や斜体字を使ってください。両方同時ではなく、どちらか一方を使うと良いでしょう。
• 表示している画面の出力の書式やボタンやメニューのラベルのような画面の文字を選んで、持続的に使用してください。Wikiにスタイルの約束事を説明したページを用意するといいでしょう。
• 互いに独立している記述は、数字なしリストを使ってください。もし、考えたことのリストが展開されていくならば、文章の連続的な順序で書いてください。
• Use footnotes sparingly and only for very short additional remarks. If there is much more to say on a specific topic, put it on a new wiki page. If you want to refer to other (external) information sources, use links instead.
• Tables can greatly enhance the readabilty of structured data. If you insert a table, make sure it has meaningful cell headers and provide a caption that clearly states the contents of the table (e.g. “Table 1.2: Average distances between the planets”).

• Write proper sentences and use articles for nouns when necessary.
• Begin each sentence with a capital letter and end it with a full stop or other appropriate punctuation.
• Try to write short, clear sentences without too much recourse to subordinate clauses. When you think that you have finished your page, read it again and revise any sentence that has an overly complicated structure.
• Decide on how to address your readers. Since DokuWiki is geared towards writing documentation, you will often have to instruct your readers, how to do certain things. You can use the imperative form (“Do this!”), the we/you form (“Then we/you click on…”) or the I form (“I then add the foo to bar, using…”). Do not mix these forms.
• Check your page for grammatical or spelling errors before saving it. If your text shows many errors, it will decrease the credibility of your statements, regardless of how well-thought they may be.
• Develop your own style. Don't force yourself to write in a manner you are not comfortable with. This would only sound unnatural and be unpleasant to read..

• When you come across a term that needs more explanation, add a new wiki page for the term and link to it.
• Re-check your page before you finish it, and add links to existing wiki pages to the central terms of your page.
• Don't add a link to every occurrence of a specific term. Make the first/most prominent occurrence on the page a link and maybe add a link to the reference section.
• Provide links to the sources of images, data and quotes.
• Consider adding a “See also:” line at the end of your page. Provide links to wiki pages that are closely related to the topic of your page there.
• If you want to give pointers to external resources that have further information on your topic or that you used in writing your page, add a section called “References” or “Further information” at the end and give a list of links or other pointers (e.g. ISBN numbers). If you have not already done so in the main text, state the intent of the reference (e.g. “[site] has further hints on how to drobble a wooze with shlimpings.”).

• “An image says more than a thousand words.” It might even mean more than you intended to say. Humans tend to question the authenticity of images less than that of language. A short textual description is better than nothing at all or than an inaccurate picture.
• As with tables, always provide a caption for images, that states what you want to show with the image (e.g. “Image 3.2: Amateur photograph showing a frob shorbeling a guzz in a wuzzle.”)
• If you did not create the picture yourself, state the source (possibly with a link) and the copyright.
• Don't link images from external sites, unless when allowed to do so explicitly. This steals bandwith from the site hosting the image. Upload the image to the wiki, if you can.
• If the picture is bigger than roughly a third of a screen page, use a link with resizing instructions to insert a thumbnail.

Please add comments, questions or suggestions for this style guide here. If you feel confident, make your additions to the style hints above directly. — ChristopherArndt 2005-09-27 00:44

Would be interresting to have some best pratices at choosing right namespaces structures