Doc Your Tool: Creating user-friendly documentation
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
Organizers
This project encourages participants to write user-friendly documentation at the Wikimedia Hackathon 2024 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]
 | The Friendly space policy applies to this program. |
- 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.
- Get started: follow these instructions.
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]
- Development Guidelines
- How to make merge requests:
- Wikimedia Developers Portal
- Toolhub
Additional technical writing resources[edit]
- Wikiversity Technical writing
- Google Technical Writing courses
- Documentation-driven development
- Wikimedia Technical Documentation Team
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).