DokuWiki

It's better when it's simple

User Tools

Site Tools


tips:good_style

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
tips:good_style [2011-02-09 12:00]
lupo49 old revision restored
tips:good_style [2016-11-20 03:01] (current)
dhurt [Page structures]
Line 4: Line 4:
 These are a few hints on how to write a good wiki page. These are a few hints on how to write a good wiki page.
  
-===== Page structure =====+===== Page structures =====
  
   * Begin your page with a first level heading with a meaningful title.   * 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.   * 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.   * 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 [[:syntax#sectioning|sections]] by adding second-to-fifth level headings.+  * If your text is longer than a few (3-5) paragraphs, consider dividing it up into [[:wiki:syntax#sectioning|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.   * 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 [[#references|below]]).   * If you have many links to other wiki pages or external resources, add a special section with further references (see [[#references|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.   * 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.   * Try to avoid overcomplicated namespace structures. Try to use short, easy to remember namespace names.
 +  * Consider utilizing the [[plugin:qc|Quality Check Plugin]] as a wiki owner or contributor to assist in page structure and text formatting.  
  
 ===== Text formatting ===== ===== Text formatting =====
Line 19: Line 20:
   * Emphasize single words or short passages of text by using **bold** or //italics//. Choose one of them and stick to your choice.   * 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.   * 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 [[:syntax#lists|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 [[:wiki:syntax#lists|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 [[:syntax#footnotes|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 [[:syntax#links|links]] instead.+  * Use [[:wiki:syntax#footnotes|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 [[:wiki:syntax#links|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").   * 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.   * Large tables tend to be very hard to edit. Consider representing its data in a nested list instead.
Line 44: Line 45:
 ===== Images and other media ===== ===== Images and other media =====
  
-  * "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.+  * "An image says more than a thousand words." It might even mean //more than you intended// to say.((Also, you can not express this quote as a picture, can you?)) 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.   * 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.   * 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 [[config:fetchsize|caching for external images]] is disabled.   * 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 [[config:fetchsize|caching for external images]] is disabled.
-  * If the picture is bigger than roughly a third of a screen page, use a [[:syntax#images_and_other_files|link with resizing instructions]] to insert a thumbnail.+  * If the picture is bigger than roughly a third of a screen page, use a [[:wiki:syntax#media_files|link with resizing instructions]] to insert a thumbnail.
tips/good_style.1297249206.txt.gz · Last modified: 2011-02-09 12:00 by lupo49