GSoD: remove barriers to entry for contributors and users

gsod-2019
#1

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.

Related material

Mentors

1 Like
#2

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.

1 Like