The ODK suite contains our most well-known and widely deployed tools. These tools support the most common use cases, are proven at scale, and are compatible with a large ecosystem.
Project description
It is currently difficult for both new users of ODK tools and for new contributors to the ODK docs to navigate the documentation. This project will involve reworking the contribution process as well as the documentation structure.
On the contributor side, we have a very thorough guide at https://docs.opendatakit.org/contributing, but it’s overwhelming to newcomers. If someone can’t get started, we have a problem! We’d like to enable contributors to make minor changes to the documentation without having to read an enormous guide and set up a development environment. We are open to changing some of our tooling to make this possible.
The core team that writes much of the documentation is often focused on describing a particular technical feature. We don’t always have a chance to take a step back and ensure that the content is logically ordered and our language is consistent.
Part of this rethinking of the documentation structure will involve developing processes that allows the core team to keep the docs easy to understand and consistent, adding documentation to address existing issues (https://github.com/opendatakit/docs/issues) and filing new issues describing content gaps.
GitLab pages support sphinx: https://gitlab.com/pages/sphinx (maybe GitHub pages support it too, I am not sure). If the documentation is hosted on GitLab pages, then it can be edited online (from the web interface of GitLab). This could make it more easy for newcomers or for making quick fixes, because you don't need to setup a local documentation environment in order to contribute proposed changes.
For this part we can look at the best practices of other organizations/projects. Some of them are even part of GSoD. For example it can be a policy like this: for each change in the code you should create an issue that requests a specific update on the docs. This tries to make sure that the docs are kept up to date. But this still does not solve the problem of the consistency of the docs (having the same style, the same level of detail, etc.) So a review of the docs may be needed after each major change or before each release.
I think that the documentation right now lack a series of tutorials that build on each other, from the most simple to more advanced. The first tutorial should be how to build the famous "Hello World" application on SDK. This is the most simple application that can be built with ODK. The second tutorial can add something more to it, and so on. Of course, you cannot cover all the features with basic tutorials, but this helps newcomers to get started easily and to get an idea about what is SDK and how to work with it.
@Dashamir_Hoxha Thanks for sharing your ideas. Given that all our infrastructure is on GitLab GitHub, it'll be difficult to move the docs to GitLab. Can you think of a way we can support quick edits without moving from GitHub?
As to the tutorials, we have a Getting Started page. Have you given it a try? If so, what changes would you make to get it closer to your ideal "Hello World"
GitLab and GitHub are very similar. In particular, they allow you to edit online and to submit pull requests (called merge requests on GitLab). If changes (accepted commits) are followed by automatic documentation update (regeneration), this would be great. Even periodic manual regeneration of documents (triggered manually) would still be Ok. I believe it can be done with GitHub as well, but I don't know how. In GitLab it would be something like this: https://gitlab.com/dashohoxha/101-problema-programimi/blob/master/.gitlab-ci.yml
It seems to me that GitLab pages are a bit more advanced and flexible than GitHub pages, but I may be mistaken, since I don't know all the features and details of GitHub.
I have just looked at it, I have not tried it. It seems a bit generic to me, does not tell you how to build an example application. "Hello World" is not ideal but is the smallest possible example that works. It does not teach you much in itself, except maybe for how to setup your working environment, but it is supposed to be followed by other incrementally more advanced working examples.
Technical writers can now submit their applications to the Season of Docs program administrators. The application form is available at https://forms.gle/Fxr2nW4TCiyESHbo8 and applications close on June 28th.
If you are willing to share your project proposal in this topic, project mentors can help you refine your proposals!