Google Season of Docs 2024: Update docs.decidim.org to 0.28 redesigned version #12640
andreslucena
started this conversation in
General
Replies: 1 comment
-
Great Project. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
The Decidim Association is applying for the 2024 Google Season of Docs, a grant for supporting open source collaboration with technical writers.
We’re looking for a technical writer to help us improve our project’s documentation.
How to apply
If you have any questions or want to apply, please send us an email to jobs [at] decidim [dot] org with the subject “Technical writer”. You have until April 20th to apply, and we’ll make a decision by May 2ndUpdate: This year Decidim wasn't selected by Google as a participant of GSoD. We probably will apply next year.
About our organization
What is Decidim?
Decidim (decidim.org) is a digital platform for participatory democracy, built entirely and collaboratively as free and open source software. Decidim is a framework built in Ruby on Rails, that allows anyone to create and configure a web platform to be used as a political network for democratic participation. The platform can be deployed by any organization (local/regional/national governments, associations, universities, NGOs or cooperatives) to host large-scale citizen participatory processes for strategic planning, participatory budgeting, public consultations and collaborative policy-making. The project was launched in 2017 in Barcelona and, 7 years later, there are more than 450 active Decidim instances worldwide, in more than 30 countries. Examples of this global interest are the Helsinki City Council, the Mexico City Government, the New York City Civic Engagement Commission, the French National Assembly, the Federal Government of Brazil, the cities of Kakogawa in Japan and Rosario in Argentina or the European Commission.
How is the community governed?
Decidim Free Software Association is a non-profit association, responsible for the governance of the Decidim community. It was created on February 16, 2019 in an extraordinary assembly, with the approval of the statutes and after a participatory process. The mission of the Association is to contribute to the democratization of society by building technology, methodologies, practices, standards, actions, narratives, and values, in a free, open, collaborative and reflexive way. The Association is the formal part of Metadecidim, a non-profit organization that serves as the legal arm of the community. It has the function of guaranteeing compliance with the social contract and community participation in the design and development of the code.
How is the Decidim community organized?
The Decidim community, called Metadecidim, is formed by people and organizations that use the software and contribute to its improvement. All those people, companies or public institutions that have some relation with the Decidim software are part of the community, anyone can be part of it. The members of the community can participate and contribute to improve the software by reporting bugs, proposing new functionalities, improving the documentation, participating in a working group, etc. The community counts with the participation of people from all over the world. Proof of this are the more than 30 languages in which Decidim is translated, translations that have been made collaboratively by members of the community. ### About Decidim Doc Redesign project
The problem
This year, the Decidim software has undergone a complete redesign, on the user and administrator sides, which is not reflected in the documentation. Several new features and all the screenshots are deprecated on the 0.28 version of the documentation, which makes it difficult for newcomers to understand how the software works. The documentation lacks up-to-date examples, images, and other necessary information. It's difficult for our users to get started because of the steep learning curve. As a result, we are losing new users and seeing an increasing amount of questions in the community channels that could have been avoided with an up to date documentation. Our community will be happy to step in and help with the updates, but we need someone dedicated to the project to audit, organize the work and fix the problem.
The project's scope
The Decidim Doc Redesign project will:
Work that is out-of-scope for this project:
This project will not revamp the global architecture of the documentation.
This project will not change the documentation for previous versions of the software.
This project will not create any GitHub tutorials; instead, the “How to contribute” documentation will link to existing material that is relevant and helpful.
Organize a hackathon with the wider Decidim community to encourage and help them use Github to improve documentation.
Long-term, Decidim would benefit from processes to ensure that documentation does not go out of date, but building a process is beyond the scope of this project.
We have one strong technical writing candidate for this project, who knows the product well and can be directly operational, and we estimate that this work will take seven months to complete. We also identified potential volunteers within the community willing to help update the documentation and participate in the hackathon organization.
Measuring the project's success
Decidim documentation has 19 contributors, and most of them are inactive. We believe that this improved documentation and resources will result in more pull requests from new contributors. Our contributors currently use GitHub issues and Decidim Element channel to raise issues about the documentation. We would consider the project successful if, after the publication of the new documentation:
Timeline
The project itself will take approximately six months to complete, as we assume the tech writer will put in part time hours (7-15 hours/week) during this time. Once the tech writer is hired, we'll spend a month on documentation audit, then move onto the content creation for the doc screenshots, and spend the last few months focusing on updating and reviewing the documentation.
Project budget
Additional information
Initially the documentation for the project was only on Catalan and through a Google Doc that was distributed through PDFs. Rapidly we found the limitations for this approach and since 2018 we are using Antora for our documentation website. All the source code is available in a git repository. In 2022 our lead developer updated the content of this website and we made internal reviews by the Product team to improve these pages. In the last months we are integrating the Vale linter for prose, to have a consistent editorial style guide.
The Decidim association has never participated in the application of the aforementioned grants from Google.
Beta Was this translation helpful? Give feedback.
All reactions