Best practices for using MediaWiki

Getting a MediaWiki wiki set up and supporting its use inside a group or organization can some times be a challenge. How do you get more people to use your wiki and how do you become confident in talking about it to others? This page attempts to cover a few aspects and best practices for establishing and using MediaWiki. It is incomplete and additions are welcome.

The genesis of this document was a session held at the Enterprise Mediawiki Conference in the Spring of 2017. There MediaWiki administrators, developers, and users came together to share best practices.

Understanding the wiki way[edit]

Wikis are similar to other systems of managing information via web pages. Content is added via an editor and viewed at a URI. Concepts such as "pages" and "categories" are found in many systems. However, the philosophical underpinnings of wikis differ from their more traditional counterparts. These differences, and arguably benefits, can be described as "the wiki way". So what does that mean?

Information lives in one location - no copies in email archives, file shares, silo "collaboration" sites, etc.
- e.g. Document_(draft)_final-2017-02-14_FINAL-revised.docx
Information is always being improved - pages are dynamic, not usually finished, documents
Information is annotated to notify readers of its status
- tag an article as 'draft' or 'historical'
It is ok to have a draft (and mark it as such)
- Also, all documents are always approaching out-of-date-ness, and wikis are more apt to resist that
History and revisions in 'public' (transparency)
Documentation is auditable - it is easy for anyone to track when a certain phrase was introduced
Normal business controls (version control) are relaxed in place of social regulation and history transparency
It is easy to undo mistakes, making for a safe environment for beginners
Anyone can edit any article
No one (individual) owns content
- Talk pages and email can help sort out confusion
- Watching a page gives some people comfort that they can stake out their space and be kept aware of updates to content they are concerned with
Everyone has the responsibility for content (if an error is found, each person has a responsibility to correct it)
Sharing something in the wiki is better than nothing
See an error? Anyone can fix it right away.
Made an error? It's ok: be bold
A wiki is a way to crowd-source knowledge - The whole is greater than sum of parts
People navigate by search and links in context
Content is always being improved and discussion can happen right alongside the content. This helps to identify clear "known unknowns"
Assume good intentions by all editors (assume good faith edits, but all actions are recorded)
Collaboration is an assumption
Simple, consistent formatting is possible with little markup. Can be extended with consistent templates and forms.
Collaboratively developed combined knowledge
Conversation platforms can be used to germinate ideas
Ideas are synthesized and collaboratively developed on a wiki
As content is developed and matured, it could be delivered on a more static platform (making wikis great for drafting or staging phases of a documentation process)
There is a push to publish first and review later (cf https://meta.wikimedia.org/wiki/Cunningham's_Law )
Specific, narrowly-focused content (well factored content)
Relationships between information can be visualized and leveraged
Transparency - allow everyone to see information, builds trust, and surfaces issues.
Attribution/Accountability - gives credit to contributors.
Ability to synthesize topics, share information outside of formal tasking, formal role.
Make it easier to fix mistakes than making it difficult to make mistakes - more and better content this way, over time (loosen authoring bottlenecks)

How do you sell the idea of a wiki?[edit]

Often when making the decision to use a wiki for a group or organization there will be a need to have agreement from different groups. Leadership will have concerns over cost and scaling. Subject matter experts will want to know how to best organize their information. Other teams will want to know about other successful groups. There's even the possibility that a formal approval process will be needed.

Who are these various 'customers' and how might you approach them with the idea of using a wiki?

Bosses[edit]

MediaWiki is the global standard, used by hundreds of millions of people
Using the experiences of other similar and/or well-known organizations can be persuasive.
- The CIA uses it! - so it is secure enough
- NASA uses it - they literally send people into space
A wiki allows us to work topically, not organizationally
A wiki helps to avoid duplicating content
Highlight existing success stories of wikis
A wiki allows you to reuse content in many different ways - prevents repeat data entry in multiple systems
- You can document information in the wiki, then query the wiki to see what is documented
Content that is itself complex (like policy) or content that explains a complex process requires a "canvas" - a web page is the best modern "canvas" type (compared to documents, presentation slides, etc.)
Wikis are the best tool for managing a collection of co-authored webpages
Wikis are a fantastic collaboration tool with a tremendous amount of transparency - all changes are documented as well as who made them
It's free software - both in cost and in license
There is commercial support from dedicated vendors and consultants
- e.g. Professional development and consulting
There are turn-key hosted solutions (Software as a Service) so no requirements on infrastructure.
Call it "knowledge management" and explain how it helps achieve that
Discuss the concerns over "out-of-date-ness" of a document with time. With non-wikis you have a downward slope which often ends up with the document being known to be out of date by all members of the community. But you also know fairly certainly (assuming strict publishing requirements) that nothing was incorrect *at the time of publishing*. With (healthy) wikis you will see that inaccuracies are quickly fixed, but you have the risk that something inaccurate could be pushlished. Displaying this graphically it's pretty easy to show that wikis are lower risk.
Cross-checking and reviews decrease errors and increase safety
Version control of documents is not an issue
Low cost, easy to set up, easy to eliminate if it doesn't meet expectations.
Simple, low-cost way to make content available enterprise-wide
All edits attributable in full history

Stakeholders[edit]

By having a long term view of sharing information, stakeholders will realize that an investment today will pay off in spades later. A wiki requires minimal investment and can quickly show it's value.
You're not locked-in; not bundled with something expensive; open source; can import/export to other formats
Future upgrades will be free so we won't abandon this format on you
Storing content as data allows for fine-grained content re-use - it saves an author time, once they see various single-source content visualizations in action
Removes "silos of knowledge"
Converts data/information into knowledge (capture the "why")
The goal is to provide quick access to correct information
Solution to the problem of loss of company knowledge when employees retire or leave the company
MediaWiki has science-enabling features: equations, footnotes, links, templates, categories which can add value to texts that already exist and make them more interlinked, discoverable, reusable. This helps to build peer review and reuse of sources.

Peer teams[edit]

If you are a proponent of using a wiki, use it yourself and share with people whenever they need something from you.
Make using the wiki part of a process - content ages quickly unless it is part of a process.
Link directly from the app you are documenting; every field label in one of the programs your organization uses should link to its wiki article
Once the wiki is up and going it will save you time over other forms of documenting and sharing information
Once a portal is up that belongs to a team, burden of maintaining can be shared, team members can rotate out but the portal can continue

How to get others to embrace the wiki way?[edit]

Support those who show up with content
Find the champions who are eager to use the wiki and have the ear of others in a team or department
Have good examples - If using something like Semantic MediaWiki or Cargo, explain how the data can be queried and displayed once the pages are created
Listen and understand workflows
Ignore doomsayers
Illustrate success, if not locally then by referring to Wikipedia
When entries can be aggregated dynamically, people feel like they have contributed to something bigger than themselves. Lists of popular or recently added/edited pages easily visible can help show contributors impact
Create a feeling of community - help each other and keep your community engaged with events and one-on-one hand holding.
Be adaptive, listen to your community needs.
Provide a proof of concept
Altruism for knowledge sharing - share for others - be of service to others - leave a legacy
Use VE, or break down the process of creating and editing pages across multiple sessions ** (have everyone create a page title and summary, then outline, then content)
Marketing - everyone uses Wikipedia, draw parallels - same benefits of Wikipedia but inside a protected environment.
Show them how easy it is to use and the advantages to using a wiki
Training sessions and editathons with free food
Create "hooks" where valuable information is only found in the wiki
Encourage! Give badges, accolades, praise.

For an existing wiki[edit]

Point to successes elsewhere within the wiki
- Explain how the wiki has grown, the costs and investment needed by other groups
Wikipedia - strangers on the internet can make a top 5 website? Now imagine that inside an org where folks are paid and you can give them a call
Channel request for "We want our own wiki" to consider sharing space on an existing wiki - more eyes, fewer silos, more value for users of the wiki
Help orient people with an introduction to the wiki by showing existing content and how to edit
Try to expand uses - convince offices, projects to use for providing easily findable information
If your information is in the same place as another group's, there will be unexpectedly helpful ways in which cross-pollination will help

For a new wiki[edit]

Develop a structure to the information early in planning
Have smart defaults when configuring forms, templates, and pages
Create a demonstration wiki or provide mockups on how the information might be organized.
Demos can be time consuming. If someone gives you a spreadsheet or a few existing word docs, it’s easy to create a few example pages out of that content - to let them see their knowledge transferred to the wiki
"In-person" training for new folks
Focused demo that is related to the audiences concerns - not a wide "here's all the things the wiki can do"
Whenever possible, bootstrap the wiki using a decent size set of pages to form a critical mass of value
Encourage and support excited users ("Look how many pages I created vs that other way") - these folks will be your best salespeople!
Provide economical decision to edit (organic growth)
Create a community of contributors
Define who can see and edit, and push as much as you can toward openness
- More openess in your org makes it easier to share and find and creates less maintance
A charismatic leader can help redirect content from email to wiki
- Develop services that creates wiki pages from email.
Take your time to design your entity classes. Use appropriate tools; expect the classes to change

Open source strengths[edit]

MediaWiki is open source. That can be a familiar advantage in your group or can seem foreign and scary. There are some benefits to open-source listed below.

Flexibility
Data portability
Extensibility
Longevity
Continuous development
No subscription contracts
- Not so much the money - but the jockeying of salespeople, timing of renewals, bids for other products
- Avoids vendor lock-in
- No licensing costs
- Low cost, access to a much greater community of developers, tech people than you could afford to pay
Extending the value of everyone's work by sharing it.
Knowledge management should not be within a closed source system
Inherent transparency
Less danger of malicious code
Easier to understand/debug how features work
Builds on each others' success by leveraging teamwork
Anyone in our organization (or our field), with similar needs, could change the software or an extension
Often much more stable

Why MediaWiki[edit]

It is one of the oldest, longest lasting, bedrocks of wiki communities
It is the foundation of what could be the largest most successful social movement - Wikipedia and its sister projects
One that acts in grand transparency
One of the best funded open-source wiki projects by far
Has a capable security team
Combination of capabilities like recent chages, watches, what links here and categories helps cope with an environment where anyone can edit anything, you can always garden them back in with those tools.
Integration with Wikimedia Commons - can have quick access by insta-links to the materials there
More chance of some of your users already being familiar with it
There's an active and vibrant community with multiple venues for discussion and help, yearly events, and active development.
Very familiar for content consumers. Designed learning curve for content providers.

Differences in using a wiki inside an organization[edit]

Anonymous editing is often not allowed or very rare
Access can be restricted for certain content
Being able to delete content is an assigned right of certain staff (not spread across the community of contributors)
Easier to sell; almost everyone, including senior managers are familiar or at least aware of Wikipedia. If it's good enough for Wikipedia and it doesn't cost anything, it will probably be good enough for us
Accountability in the enterprise
Be more sensible in regards to data security issues than a public wiki
Due to the relatively much smaller user numbers, there needs to be more targeted generation of content. Especially at first the pages won't 'make themselves'.

Other points[edit]

Gameification and positive feedback loops are useful to spur contributions
Use PageForms
Top down support needed for success
Use open source web analytics to learn more about your wiki and your community of users
Don't be afraid to predesign your wiki structure / classes. Keep in mind, that this design might change
Don't be afraid to make clones of your wiki to test things out before going to production
Organic - everyone can potentially add value if they want to contribute and extends functionality of the entire wiki