MediaWiki is our recommended tool for Documentation

Overview

If we take our tool workflow as a narrative, we began by setting a timer with BackBeat, then we had an informal, real time discussion in Mattermost which turned into a longer form, team-wide exploration in Loomio — where we agreed to take on a specific task. The task's progress and its to-dos happened in Trello and (maybe) using some of the tools we find in NextCloud. What do we do at the end of this process? We document what we have learned, share it publicly as a commons and then use this knowledge to kickstart new iterations. The tool we use for documentation is Mediawiki.

About MediaWiki

You've used Wikipedia, so you're already familiar with MediaWiki — the software it runs on — but maybe not so much how it works and what advantages it offers. MediaWiki is a free software "engine" originally developed for use in Wikipedia which has since been use for other Wikimedia projects, as well as a host of other sites. We use it for documentation as it provides an easily searchable database for the knowledge we generate as collective.

The following passage is extracted from The Wiki Way:

The wiki way is to make bad edits easy to correct, rather than hard to make. It is the whole reason for creating a wiki in the first place, rather than a website (like most websites) where editing is only allowed by a handful of approved editors, and any changes desired by the larger public must be submitted as suggestions to, and then implemented by, those authorized editors. Such a system makes the process of getting desired changes made more cumbersome, and thereby makes members of the public less likely to bother with them.

For example, most users to a news website such as the New York Times who see a typo in an article are unlikely to go to the trouble of notifying the webmaster. That could require a number of steps such as finding the webmaster's email address, composing a message, etc. Who knows; perhaps many other users have already reported the same typo, and the extra effort involved in making another report is wasted. A wiki, on the other hand, allows users to simply hit an edit button and immediately make changes by themselves. In practice, this way has resulted in at least one high-quality product: Wikipedia.

Besides the ease with which we can edit our knowledge commons, MediaWiki's engine also allows us to categorize our content in a way that mimics our main areas and subgroups, as in the other tools.

As you will have noticed, our wiki looks much neater than Wikipedia, this is because we use a skin (a custom graphic interface) called Tweeki. Tweeki makes our wiki more attractive, mobile responsive and, also, integrates features such as semantic wiki, which can allow us to connect with other wikis to create explicitly interrelated networks of knowledge.

What we use MediaWiki for

We use MediaWiki to document and open-source our processes in a platform that is easily editable by our team. Although the wiki is openly accessible, edit access is by default limited to DisCO members from the Dating Phase upwards, as well as members of our Stakeholder Board.

As we build the collective, many of the practices prototyped by DisCO (and its governance model) will be ported over to the graphic and coding collectives and other offshoots, but these will have their own adaptation of the governance model and processes. Keeping all the info in the same wiki allows us to keep all common info and procedures together whilst cataloging differences. In its totality, it can become a publicly accessible set of tools for Open Cooperativism and Distributed Cooperative Organizations grounded in actual practices.

The wiki also allows us to organize its content through categories (roughly corresponding and expanding on our main areas and subgroups) and to hyperlink to specific sections of wiki entries, as we will see below. These and other features make the wiki extremely useful when searching for information.

There will be a close and synergistic relationship between the wiki and the handbooks. Much of the content already existing on the wiki will be updated and adapted for the Handbooks. Similarly, new material written for the Handbooks will be incorporated into the wiki. The difference is that the Handbooks are "the mixtape" of the Wiki's content. They give you the essentials in a sequential and long-form narrative way. Once you are familiar with this info, you may prefer to refer back to the Wiki directly. The wiki also goes into a lot more detail on certain parts of the handbooks and is updated more regularly. It also contains a host of entries on procedural details for things such as Markdown, mutual support, community rhythms, etc. which fall outside of the scope of the Handbooks. To use another musical analogy: the Handbooks is the Greatest Hits album, while the Wiki is the box set (with all the b-sides and rarities!)

What MediaWiki is (and isn't) for

MediaWiki IS for:

A searchable repository for information
A way to hyperlink to specific sections of information within a text
An easily editable platform for tutorials and team procedures
A place for non-team members to offer feedback and suggestions through the discussion pages

MediaWiki ISN'T for:

One on one conversation, off-topic stuff and quick check-ins (use Mattermost)
Working circle real-time communication (use Mattermost)
Having long discussions, making announcements everyone needs to see and acknowledge or voting on decisions (use Loomio)
Figuring out how we work and how we go forward (use Loomio)
Workflow and project management (use Trello)
Specific tasks (use Trello)
Attaching documents that have to do with specific tasks (use Trello)
Setting precise deadlines in tasks (use Trello)
Attaching readily available documents for larger tasks (use NextCloud)
Writing collaborative documents (use NextCloud)

Screenshot from MediaWiki's Welcome page.

How we use MediaWiki

Suggested bookmark for BTBW: DisCO Mothership Wiki Homepage

Although you can find plenty of tutorials in the resources section below, we will now explain the two basic procedural functionalities of the wiki: organization and creating and writing new entries. We'll also touch on other additional questions at the end.

Organization

Organization in the Wiki is mediated by categories: every entry has at least one of these.

These categories, as you would expect, also follow the logic of our Areas and subgroups. These are nested hierarchically. So, for example, if you go to the Community category (one of the main areas), you will see that it hosts subareas. It is like a category tree.

Just like Mattermost and NextCloud, the Wiki contains some additional beyond the "basic set". These have been created using common sense and include:

Governance: Governance is intrinsically tied to the community category/subarea, but we have reserved this wiki category for our specific governance model and its version history.

Tools: Resources on all our convivial Tools. Think of it as the expanded version of Book 5: Convivial Tools.

GMC-DisCO REVISE: This is a Wiki procedural category to highlight pages coming from the GMC wiki that need to be revised and adapted to the DisCO Mothership Wiki. It will be retired once the wiki is fully updated.

You can find the full list of wiki categories here.

How to categorize new entries or create new categories

This is very simple. At the bottom of the wiki entry you are editing you add the necessary categories. The syntax is [[category: COMMUNITY]], so any entry that's part of the "Community" category will have the following line at the bottom of the edit window: [[category: COMMUNITY]]. Here is what the bottom of the edit window looks like for the governance model:

Beware: categories are VERY case sensitive. This means that if we have an existing "Love Work" category, if you type "love work" or "LoveWork" or anything different, it will create a new category. These are a (minor) pain to clear up, but watch your step.

Here is a great short video on MediaWiki categories.

Creating categories is very easy. In fact, you can create them by mistake, as in the example above. In general, we want to keep to the main subgroups and the extra categories listed above. Do you feel a new wiki category ought to be created? Have a good think about whether it's justified or if it would clutter the structure and raise the issue in Loomio.

Creating and writing new entries

Creating new entries is as easy as creating categories, whether it's intentional or not! That's the beauty of wikis — you can do most of your work just by typing in the editor, no need to click on anything. To create an entry you simply use double brackets around any word, and this will create an entry. Say that as I'm typing in another entry, I want there to be an entry on Scuttlebutt. I'd then need to surround it in double brackets as such: [[Scuttlebutt]]. This will create the infamous Red Link, which basically means "hey, look at me! Someone created me but then didn't give me any love, HALP!!"

So you would then have to write the entry. If you don't want to get sidetracked, you can list it in the DisCO Mothership Wiki Trello card under "New Wiki Entries".

Once we are clear on what wiki entries we want to create, anyone can get started in them and signal the rest of the team to contribute. Ideas can be exchanged in Loomio or Mattermost and the entries are "living" entities, always ready to be improved and updated.

So what's the criteria for creating new Wiki entries? If we have learned something useful and it needs to be referred back to, create an entry. The wiki can be as expansive as we want as long as a) New entries are not redundant (use the search function first) and b) They logically fit within the existing categories. Again, ask your DisCO pal if you have any doubts.

Once we are clear on when and how to create entries, let's talk about writing in MediaWiki. As mentioned above, the beauty of MediaWiki is that you can practically do everything with your keyboard. There is some bad news though. Wikitext, (the syntax/code) used for MediaWiki is frustratingly similar to Markdown, but not the same. This is like learning Portuguese and Spanish at the same time. Similar but very different and you may get confused. But hey, you're a DisCONaut after all, this is not beyond you.

The best way to learn is from our How to Edit page, or from MediaWiki's more advanced entry on formatting. Please, take a look at either of those links and play with the code in our Sandbox. What follows are the very basics to give you a rough idea.

The beautiful thing about MediaWiki is how it auto-generates a Table of Contents (TOC; located on the right column in our wiki or at the bottom if you're reading on mobile). It does this based on headings — any entry with more than four headings will generate a TOC:

One equal sign on both ends of a sentence will autoformat as heading 1

Heading 1 Example

Two equal signs on both ends of a sentence will autoformat as heading 2

Heading 2 Example

Three equal signs on both ends of a sentence will autoformat as heading 3

Heading 3 Example

...and so on. This will render something like this (notice the headings on the text and the TOC on the right column):

So, imagine that you've already structured your document with headings. Now you can write the text in between the lines.

One equal sign on both ends of a sentence will autoformat as heading 1

Top level heading (H1)

We can write some text here

Two equal signs on both ends of a sentence will autoformat as heading 2

Second Level Heading (H2)

Followed by more text here

Three equal signs on both ends of a sentence will autoformat as heading 3

Third Level Heading (H3)

And more, over here

And this is where we begin a new section.

The code above renders like this (subheadings are nested in the TOC, you need to click on their parent headings to unfold them. Here we've clicked on Headings 1 and 2 to unfold 3):

You must always start a new paragraph between lines: A single newline has no effect on the layout. But an empty line starts a new paragraph.

For our final example, we will show you how to create internal and external links. Internal links, as we've explained above [[use double brackets]] (you simply add the name of the destination wiki entry between the brackets. External links use [single brackets +destination url]. Let's see how this looks like in the editor. Internally we will link to the Glossary entry. Externally we will link to a totally different page.

One equal sign on both ends of a sentence will autoformat as heading 1

We can write some text here. There's more text in the DisCO Glossary

Two equal signs on both ends of a sentence will autoformat as heading 2

Followed by more text here. There are many glossaries online

Three equal signs on both ends of a sentence will autoformat as heading 3

And more over here

Here is another heading 1

Heading 1 Example

And this is where we begin a new section.

This renders like this (notice that the internal link shows up as normal, while the external one has a little padlock indicating it's not contained in the wiki and, therefore, external:

Once you're familiar with headings, categories and how to link, you're almost all the way there. If you want a good summary of these wiki editing hijinks, Wikipedia's formatting tutorial is always a good bet. Again, try Wikitext for yourself in the Sandbox or watch the video below for a live interpretation:

Video on how to use Wikitext.

Although we recommend learning the syntax (it's faster and more intuitive), Tweeki features a really good WYSIWYG editor. Here is it (with the "Advanced" tab pulled down):

This works just like a normal editor, you highlight the part of the text you'd like to edit and use the buttons. Try it out if the syntax is not your thing.

How to use the color key

The DisCO Stack recommends an agreed-on color key to signal several things, such as status updates etc. The same color key applies to all tools in the DisCO Stack.

Below you will find the color key and the exact wiki code you need to copy and paste to implement it. ^[1]

Circles

COMMUNITY {{COM}}

NET.LABS {{NET}}

DAT.MENT {{DAT}}

STO.DOC {{STO}}

STRA.DEV {{STR}}

LEG.FIN {{LEG}}

VISUAL {{VIS}}

TECH {{TEC}}

DIWO {{DIW}}

RESEARCH {{RES}}

Top-level status

hello hello Deliverable up to defined status/quantity

hello hello 2nd priority deliverable, dependent on time/resources

hello hello Planning, groundwork and pre-design

hello hello Planning Only

hello hello Accounted as LoveWork, but part of project deliverable reporting

hello hello Accounted as CareWork, but part of project deliverable reporting (DisCO LABs pilot development for DisCO MOTHERSHIP and Guerrilla Media Collective)

Progress

Hello {{PCT100|Hello}} Deliverable COMPLETED

Hello {{PCT75|Hello}} Deliverable mainly completed. Follow up tasks pending.

Hello {{PCT50|Hello}} Deliverable Currently Underway.

Hello {{PCT0|Hello}} STARTED/PLANNING STAGE. Needs to get underway.

Hello {{PCT-1|Hello}} Deliverable CANCELLED from current budget (but not from the DisCO Project). Moves into next funding/project.

Additional MediaWiki Tips and Tricks

Beyond the basics, here are some additional items to make the best use of the Wiki.

Conversion:

If you want to convert some existing text, you can copy and paste it onto a converter like this one. Now, your text must be in html before converting to wiki. Say you want to "wikify" something written in Google docs. You will copy and paste your text in the right hand side of this editor. Html code is displayed on the left. Copy the code on the left and paste it in the wiki converter, then copy the wikitext and drop it on the wiki.

Editing sections through headings:

This is a cool Tweeki feature that allows you to edit any section under a heading by clicking on the edit pencil beside the heading. Or you can edit whole pages by clicking on the Edit button on the right-hand side of the page.

Discussion:

As we've explained above, we encourage anyone to open a discussion page on the wiki. Discussion (or "talk") pages can be created for any entries. While we normally have these discussions in corresponding Loomio threads, if you think it's better to note some observations in a wiki entry, just go to Page/Discussion. This will bring up a new editor. In the same menu, click on the "page" button again, and then on "+". This allows you to add a new topic. See here for an example.

Dark and Light

The DisCO Mothership wiki runs on default dark mode for max GothQueerness, but you can turn it to light through your browser. We, of course recommend that you use Firefox, as it's the Open Source and privacy enabled browser. Firefox has a great reader view. Either check out this article on Firefox's reader mode or follow the procedure below:

1: Go to your url bar and look for the "toggle reader view" icon. It's the tiny text/page like icon to the right of the URL

2: See the magic happen:

Enjoy!

Spam Whitelist

Trying to add a link and the wiki tells you it's spam? No problem, contact the TECH Circle and the attendant DisCONauts will walk you through the Spam Whitelist procedure.

How do I contribute?

The final and, perhaps, most important question is how do I contribute to the Wiki. The simple answer is by making it yours. The wiki is meant to be a living entity (like DisCO.coop itself!) and all of us members, whether Dating or Committed take part in its ongoing creation. If you're reading an entry and think you can add something, by all means do! Like everything else, add commonsense. Although we are very focused on categories, as long as you work within that structure, you can create entries about anything that's useful to the collective. Or, by the same token, you can add more info to existing entries.

To give an example, we have an entry on (anti-capitalist) Productivity Tools and Hacks. Have you read a good article on the subject? List it here then. Have you developed a more efficient way to format blog posts? Share it on Loomio but then document it on the wiki. The wiki is the living testament of what we learn together, and our way to pay it forward is by sharing it on the commons.

Additional MediaWiki Resources and Tutorials

As one of the longest-running (and most successful) free software projects of all time, MediaWiki documentation is extensive, if not as slick as that of the proprietary tools. The MediaWiki help page is a good place to start. Also, Wikipedia has many resources that can easily be adapted to our wiki (don't miss the Wikipedia Adventure, for example).

Main MediaWiki help page; help contents

Wikipedia's Help Page

The Wikipedia Adventure (fun interactive tutorial)

Wikipedia Tutorial

Wikitext Formatting Wikitext Cheatsheet

How to use Wikitext (video summary)

DisCO Wiki Help, How to Edit and Sandbox

MediaWiki FAQ

Differences between Wikipedia, Wikimedia, MediaWiki, and wiki

Creating categories and subcategories video tutorials

DisCO Mothership Wiki: Additional MediaWiki formatting tips