For the 2024 Hackathon, @JorisDarlingtonQuarshie and @TBurmeister want to make it easy for tool developers and technical contributors to improve tool documentation. To facilitate that, we're working on the following coordination tasks:
- Creating a project page: https://www.mediawiki.org/wiki/Doc_Your_Tool:_Creating_user-friendly_documentation
- Investigate methods for identifying tools that could use documentation or maybe have it but it's not easy to find, maybe https://toolhunt.toolforge.org can be useful here
- Creating (or updating) guidelines about:
- how to file good docs tasks
- what is essential documentation for tools, focusing on README and CONTRIBUTORS contents, like a "how to run this tool" section
- how to find and improve existing tool documentation: https://www.mediawiki.org/wiki/Doc_Your_Tool:_Creating_user-friendly_documentation/Instructions
- how to invite contributions for tool documentations for tools you maintain (building on discussions at past hackathons like T332876, T333178
For practical reasons, we're limiting the scope of this to active tools available on Toolforge, with preference for community-maintained tools. And we're focusing only on technical documentation -- not tool user documentation. If you know of actively-maintained or still-functional tools that could benefit from improved technical documentation, you can contribute to preparing this hackathon project by filing phabricator tasks and tagging them as described above. If I have tagged a task that you think doesn't meet our criteria, or you want it removed for any reason, please remove the tasks. Thanks!