tips:good_style
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
tips:good_style [2011-06-18 08:02] – [Hints on good style] 91.65.235.112 | tips:good_style [2016-11-20 03:01] – [Page structures] dhurt | ||
---|---|---|---|
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 [[: | + | * If your text is longer than a few (3-5) paragraphs, consider dividing it up into [[:wiki: |
* 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 [[# | * If you have many links to other wiki pages or external resources, add a special section with further references (see [[# | ||
* If most of the pages of a [[: | * If most of the pages of a [[: | ||
* 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: | ||
===== Text formatting ===== | ===== Text formatting ===== | ||
Line 19: | Line 20: | ||
* Emphasize single words or short passages of text by using **bold** or // | * Emphasize single words or short passages of text by using **bold** or // | ||
* 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 [[: | + | * Use [[:wiki: |
- | * Use [[: | + | * Use [[:wiki: |
* 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." | + | * "An image says more than a thousand words." |
* 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: | * 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: | ||
- | * 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.txt · Last modified: 2021-12-28 03:33 by andi