https://RustRocket.rs -- Cloud Monk Losang Jinpa, Ph.D., MCSE / MCT, https://Rustaceans.rs, Full Stack Cloud Native Rust DevOps Engineer - Rocket Framework Rust Microservices on Kubernetes-AWS-Azure-GCP

Return to DokuWiki topics, DokuWiki

Good style - Good Wiki style

These are a few hints on how to write a good wiki page. See also our hints on good DokuWiki content.

• Begin your page with a first level heading with a meaningful title.

• Nest headline levels in their correct order, sections in the second level should start with a second level headline.

• Break up your text in paragraphs by leaving an empty line between them. An average paragraph should not be longer than 10-20 lines.

• If your text is longer than a few (3-5) paragraphs, consider dividing it up into sections by adding second-to-fifth level headings.

• When your text gets longer than 2-3 screen pages, put a short abstract of the contents of the page after the first heading. When your page gets significantly longer consider splitting it up in multiple pages.

• If you have many links to other wiki pages or external resources, add a special section with further references (see below).

• If most of the pages of a namespace share a common structure add a namespace template so any new page can begin with that skeleton structure.

• Try to avoid overcomplicated namespace structures. Try to use short, easy to remember namespace names.

• Consider utilizing the Quality Check Plugin as a wiki owner or contributor to assist in page structure and text formatting.

• Emphasize single words or short passages of text by using bold or italics. Choose one of them and stick to your choice.

• Choose a style for representing screen output and text on the screen like buttons or menu labels and use it consistently. It might be a good idea to add a page with an explanation of your style conventions to your wiki.

• Use unordered lists for statements that are independent of each other. If you are developing a line of thought, write in a continuous sequence of sentences.

• 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 readability 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”).

• Large tables tend to be very hard to edit. Consider representing its data in a nested list instead.

Language

• 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.

• Setting up interwiki shortcuts can help with linking to common resources.

“An image says more than a thousand words.” It might even mean more than you intended to say.1) Humans tend to question the authenticity of images less than that of language. A short textual description is better than an inaccurate picture.

• As with tables, always provide a caption for images, that states what you want to show with the image.

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 is firstly a matter of copyright but can also be a matter of bandwidth stealing when caching for external images is disabled.

• If the picture is bigger than roughly a third of a screen page, use a link with resizing instructions to insert a thumbnail.