Best practices for using MediaWiki - MediaWiki (2024)

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.

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)

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

• 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

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

• 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.

• 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'.

• 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

• Etherpad from session that started the initial draft of this page
• The wiki way - a description of the wiki way as described for (and by) the Wikimedia movement
• Sites using MediaWiki
• Testimonials
• Enterprise hub
• What is open source? - opensource.com

Retrieved from ""