How to create a wiki page

NOTE: This is a proposal, not implemented. It takes the form of documentation for how I would like people to create a wiki page in the future once we implement it. If agreed to and implemented, then this page becomes documentation. See #13220

Choose a good page name

The page name is the part of the address that follows /wiki/ - e.g., this page name is "create."

Please think hard on the right name for your page. Some criteria to consider:

  • Short and descriptive - please choose the shortest possible name that is still descriptive. If the page is related to time, include a date following the name (e.g. membership-meeting-2016 or leadership-committee-notes-2016-10
  • No slashes (we used to use slashes in the name for hierarcy, not any more - see below for bread crumbs)
  • Only lower case letters, numbers and dashes
  • If there are two pages for the same topic, one that is user facing and one that is admin facing, try to make the names reflect that. For example "mumble" could be the name of the user facing page and "murmur" could be the name of the admin facing page (since murmur is the program running on the server). You could also create mumble-acls page to instruct admins on how to setup permissions. When all else fails, add -admin to the name of the page.

Implementation details: We would need to convert all existing names that don't follow this protocol to better names. This could be partially automated, but would require a lot of human intervention to get things right. We should also strive to create automatic redirects from old page names to new page names.

Choose a wiki type

There are only two types of wiki pages:

  1. how-to - a how-to wiki page answers a discrete question, whether it is technical or non-technical in question
  2. doc - a doc wiki page is any other kind of page (e.g. meeting notes, project page, description of a leadership body, a manual)

You can choose one or the other by adding either how-to or doc as a tag. If you fail to add on or another, you will get an error message when you save.

Implementation details - If it was possible to create custom wiki fields, I would opt for a custom wiki field. But, not sure that's possible. If we go with tags, I think we should write a simple plugin that ensures one of these two tags is entered for every wiki page and prevent saving if it is not.

Choose the topic

For how-to wikis, choose from the current list of faq types (we should review these and adjust if necessary) and add at least one as a tag.

Choose the audience

For pages specifically designed for system administrators, add "admin" as a tag so the page will be excluded when displaying wiki pages intended for general audiences.

Create a bread crumb

For some wiki pages it is useful to organize them together in a book-like format using a breadcrumb to navigate between them (previously this was achieved by naming pages with slaashes in them).

Now, you can create a bread crumb using macro by adding the following at the top of the page:

[[breadcrumb(gpg|gpg-windows:"Installing GPG on Windows"|gpg-windows-trouble:"Trouble shooting Windows GPG installation")]]

if Each item in the breadcrumb should be separate by a pipe (|). You must include the page name. Optionally add a colon followed by the display name if you want it to be different from the page name.

Implementation details: this will require a plugin to be written. I don't see anything that does this. Also, this step should happen before page renaming - so that we can first take all pages like projects/membership-meeting/2017/timeline and create a breadcrumb for them in a way that is consistent with how we envison renaming them.

Last modified 4 years ago Last modified on Dec 12, 2017, 9:15:48 AM