MediaWiki

Doc Your Tool: Creating user-friendly documentation

A Wikimedia Hackathon 2025 project

Registration
Register to participate in this program by adding yourself to the attendee lists. Registration for the in-person Hackathon in Estonia is separate. You don't need to attend the Hackathon in person to participate!

Participants
Add yourself

Photos and media
Add media here

Elsewhere

Etherpads
Add your Notes here

Reports

This project encourages participants to write user-friendly documentation at the Wikimedia Hackathon 2025 by creating clear and concise documentation for valuable tools and projects.

Overview

edit

Whether you're building something new or improving upon existing resources, your expertise can help unlock the potential of these tools for a wider audience.

Two ways to participate

edit
  • Document as you develop: As you create new tools during the Hackathon, we encourage you to document your journey alongside the building process. Use this quick documentation template to make sure you cover the essentials. This will not only aid others in understanding and using your tool but also provide valuable insights for future development.
    • Or, try writing documentation before you start developing! Documentation-driven development is a technique that can help you throw away less code. By writing docs first, you build a framework upon which you can then build more clear and focused code.
  • Improve existing documentation: Breathe new life into existing tools by improving their documentation. This could involve updating outdated information, restructuring complex instructions, or creating new tutorials for specific use cases.

Target audience

edit

This project is ideal for participants who want to contribute to the long-term sustainability and impact of the Hackathon projects and community-created tools. It's appropriate for people with strong communication and technical writing skills, and beginners interested in technical writing. This project provides an excellent learning opportunity within a supportive community.

Project activities

edit
  • Identify projects requiring documentation: Collaborate with Hackathon participants to determine which projects need user guides, installation instructions, tutorials, or API references.
  • Define documentation scope: Based on project needs and target audience, determine the type and level of detail required for each document.
  • Write clear and concise documentation: Utilize plain language, and consistent formatting to create user-friendly guides.
  • Integrate feedback and iterate: Welcome feedback from potential users and Hackathon participants to improve the clarity and effectiveness of the documentation.
  • Publish and promote documentation: Ensure the documentation is easily accessible and discoverable by relevant users.

Deliverables

edit
  • User guides, installation instructions, tutorials, or API references for tool-related Hackathon projects.
  • Documentation published in tool repositories or on the appropriate technical wiki.
  • Resolution of existing Phabricator tasks requesting documentation improvements for community-created and maintained tools.
  • Creation of well-scoped and easy-to-understand Phabricator tasks describing technical documentation needs for tools.
  • A blog post or presentation showcasing the project's outcomes and impact on the Hackathon's success.
  • A documentation guide focused specifically on tool documentation: mw:Documentation/Tool_docs

Benefits

edit
  • Increased project impact: Improved documentation leads to wider adoption and contribution to Hackathon projects, extending their reach and value.
  • Tool sustainability: Documentation helps ensure that tools can be maintained by others in the community if the original developers can't maintain them.
  • Knowledge sharing and learning: Participants with technical writing skills can mentor beginners, creating a collaborative learning environment.  Contributors interested in documentation and contributors focused on coding can learn from and help each other.
  • Community contribution: Participants directly contribute to the Wikimedia community's knowledge base and infrastructure by documenting tools.

Wikimedia-specific resources

edit

Documentation resources

edit

Development resources

edit

Additional technical writing resources

edit

Participants

edit

To add your name to this list, edit the wikitext source to add a new line and type ~~~ (The three tildes automatically signs your name after you save the page).

Retrieved from "https://www.mediawiki.org/w/index.php?title=Doc_Your_Tool:_Creating_user-friendly_documentation&oldid=6893613"