Here are some pointers for writing Wiki articles for the openhealthhub.org wiki
Top-level recommendations
-
Have a photo avatar, not the generic default ‘first initial’ colour circle. It makes you appear in the forum as more of a real person. [Set this here](openhealthhub.org - Open Health Hub is a non-profit, donation-funded, open discussion forum for health technology in the UK and internationally
-
Use your real name in the forum, this affords you credibility. Set this here
Formatting
-
Read and learn - You can look at the source text of any existing topics or posts, to see how their formatting was achieved.
-
Discourse defaults - We have set Discourse up so that, by default, any New Topic in wiki will be created with the Wiki functionality enabled, and the Discourse Table Of Contents (DiscoTOC) code
<div data-theme-toc="true"> </div>added into the topic for you. We include some example headings to get you started. -
Text - Use short paragraphs, breaking text up into manageable and readable sections. Long unbroken blocks of text are harder to read, and readers will give up on them.
-
Structure - Create a logical document structure using Markdown headings (available in the toolbar or using different numbers of
###prefixes) This structure is used to generate the Automatic Table Of Contents which is shown in the right side of the screen when browsing your Topic. -
Graphics - Use diagrams and visuals to explain concepts when necessary. Leave placeholders if you don’t yet have the right visual. This community can help you create these visuals if you aren’t good at it, just ask.
-
Lists - Use bulleted or numbered lists where this helps to itemise content.
-
Links - Use hyperlinks to link to other pages in the Wiki, and to other external sites and services. Always prefer linking to something rather than creating a duplicate of that text. Duplication is bad because it means multiple places to update, linking is good because there is only one ‘source of truth’ to update.
-
Footnote references - You can insert a footnote, with automatic numbering, using
^[footnote content]and it will be numbered and inserted at the bottom for you. This stnyntax is also available from the Composer ‘plus’ menu. -
Learn from the best - Be inspired by, and borrow ideas from, other high-quality knowledge resources on the Internet. Wikipedia is an excellent example.
Styling/Structuring Resources and References
- Markdown Guide - https://www.markdownguide.org/
- Changing the Wiki style - Change the style of a wiki post - Developer Guides - Discourse Meta
- DiscoTOC - DiscoTOC - automatic table of contents - Theme component - Discourse Meta
- Discourse Doc Categories Plugin - Discourse Doc Categories - Plugin - Discourse Meta