Event:WMA Hackathon 2025/Docs exercise

This page provides instructions for the hands-on technical documentation exercise, as part of the presentation "Intro to technical writing for Wikimedia projects" at WMA Hackathon 2025.

Before you start

You should already have a a Wikimedia Global user account (to log in to wikis), and you should be familiar with how to edit wikis.

OR

You should have completed the setup steps in the Developer Pack.

Choose your format and copy the template

Write a doc on a wiki

Log in to Meta-Wiki (this wiki).
After you log in, click your username in the top menu to go to you User page.
Create a new blank page in your User: space. You can use your main User page, or create a new subpage.
In a new tab or new browser window: go to mw:Documentation/Tool_doc_template#Wikitext
Copy the wikitext in that section, and paste it into the new page you just created in your User space.

Helpful resources:

Write markdown and publish like code

This option requires you to already understand git-based workflows. If you already know how to use Github, you can use your own account to practice. However, if you want to contribute to existing Wikimedia projects, consult the Developer Pack and Instructions for new developers (new contributors).

New to Markdown? See this guide to writing Markdown | guide de Markdown en français

Go to mw:Documentation/Tool_doc_template#Markdown
Create a new markdown (.md) file in your working directory
Copy the contents of the markdown template into your new file.

Find or imagine a tool to document

If you're more interested in practicing writing or using the publishing tools:

Pick a piece of technology you already use in daily life, and start filling in your copy of the documentation template. Use the prompts in the template to help you imagine what types of information your doc should cover.
Bonus: for fun, you could search online to see if you can find the real docs for that technology, and see what they actually cover. Do they follow the documentation principles we learned about?

If you're more interested in applying documentation best practices to real docs:

Go to Toolhub.
Browse the lists of tools on the main page. These tools are most likely to have existing documentation that you can work from.
Click a tool to go to its record.
In the tool record, look for links to user documentation and/or developer documentation. You may find them in these fields:
- "How to use"
- "Developer documentation"
- "Source repository"
- In some cases, you may have to go to the tool's front-end (if it's a web app) to find links to its documentation.

Start to fill in your copy of the documentation template, using the prompts in the template to identify ways you could change, rewrite, or reorganize the existing information. For example, consider:
- Do the current docs make it clear who the intended audience is for each page? Does each page have an introduction section?
- Can you skim or scan a page and understand who it's for, and what it would help them do? If not, what changes could help make that more clear?
- Do the current docs have action-oriented headings? Could you rewrite them to be more direct?
- Is there a clear separation between content for the tool's users, vs. content for tool developers? If there are separate pages for each audience, are there links between those pages?
- Consult the Tool Docs guide to identify other ways you might be able to improve the documentation.

More guidance and templates

The Tool Docs guide has everything you need to know about writing tool documentation, and it has links to more templates and examples of real docs to inspire you.

To get started contributing to existing projects and open documentation tasks, visit mw:Documentation/Contribute.

How to get help

During the hackathon, you can get help by sending a message on the Wiki Mentor Africa Telegram group, in the Technical Documentation channel.