Software Heritage’s Documentation: A Fresh Journey Begins!
We are thrilled to present the recently created Software Heritage documentation landing page for users and contributors at docs.softwareheritage.org.
On the landing page, you can browse the available resources and also contribute to improving the documentation!
Knowledge about Software Heritage exists in various forms, in many places and for different audiences:
- Technical documentation for partners,
- How to guides for developers,
- Source code description for code contributions,
- Presentations and videos for users and visitors,
- Articles and publications for researchers,
- GitLab tickets for contributors,
- and more.
The docs landing page, that you are able to explore today, aims to orient readers to the adapted information depending on their goal, be it discovering Software Heritage, archiving source code, searching the archive, engaging in outreach efforts, integrating the archive into their applications, or contribute to the enhancement of our tools.
At Software Heritage, the team engages in regular two-day sprints dedicated to enhancing the documentation collaboratively. Through this collective effort, we have successfully gathered information and provided content to contributors, partners, users and visitors. However, it’s important to acknowledge that we still have a significant journey ahead to offer users more hands-on resources and support.
One hard part of writing good documentation for large projects like Software Heritage is having a good understanding of the audience. In the near future, we hope ambassadors will be able to help us refine our “personas” (fictional characters to represent our different user types). This should help us better know what to write and, hopefully, which parts should be prioritized.
Finally, it is possible to fix and contribute to the documentation in a quick and easy way. Almost all pages on docs.softwareheritage.org have an “Edit” link which points right to a web editor on the Software Heritage development platform. Fixes of small mistakes or short improvements can be proposed in a matter of minutes with the GitLab Web IDE. One just needs to create an account and edit the page on the swh-docs module. We had to set up manual approval for account creation to thwart spammers, so feel free to send us an email if we have missed your request.
👉 https://docs.softwareheritage.org/devel/contributing/tutorial-docs-contribution.html
During the ambassadors workshop in June, Lunar guided the Software Heritage ambassadors with a tour of our resources and together they identified some aspects that could still be improved.
A heartfelt thank you goes out to all ambassadors who attended the collaborative learning experience!
Our gratitude also extends to the dedicated community members who are actively engaged in the ongoing process of improving the documentation.
With their help, we will continue to enhance and expand our documentation to better serve the diverse stakeholders in the software preservation and sharing community.
We invite you to be a part of this journey to make Software Heritage an essential resource for software preservation and sharing. Thank you for your support!