Part 2: Project Operations: Documentation

[Erioldoesdesign]

Introduction

Documentation in SROSS serves many purposes such as helping users navigate through the software and discover features, it helps resolve installation issues and dependencies, it enables a better way to package the software, it also helps make the code easier to access by other developers when the code is documented well. Documentation takes various forms, from a simple read-me to tutorials, workshops, case studies, examples, training, videos etc… all serving the purposes mentioned above. Software teams believe that documentation enables their users to identify and understand what the software offers while evaluating choices. One respondent claimed that “it is a way into the future in a way that other people can continue if docs are good”. Even though most of the softwares agree that it “promotes stability in project usability - allowing users to access workflows smoothly”, not all softwares are equal when it comes to managing and strategizing documentation.

State of documentation in SROSS

There’s an entire range of documentation from pretty exhaustive user guides and reference manuals to being incomplete, outdated, having sparsely populated information which one participant called “a train wreck”. Some projects tend to describe all the concepts around their software in their documents but, critically, not how to use it. Some have their features documented but do not have anything intentionally constructed for user onboarding. One project was surprised to see people’s personal accounts of using and getting started with the software when searching for their documentation. Most of the projects have their documentation in a state of continuous work-in-progress and never up-to-date. Aspects of documents such as access and discoverability are also identified as work in progress. One of the maintainer participants mentioned that their “documents, books and guides on usage of the tool is part of the improvement process”. There were also some projects that did not know the state of their project's documentation which, given the strong connection projects made between documentation, onboarding, and usability, made us wonder about how else those projects might incorporate user-focused practices.

Response to documentation

Different projects respond differently to the need for documentation. Projects rely on documentation as a reliable plug to fill in the usability gaps, depending on the level of usability of their softwares. Documentation comes to the rescue when it’s a lot harder to get something working on the UI, the usability is still clunky, and there’s no other solution in sight. Maintainers prioritize documentation when there’s a lot of questions and conversations from the users which need to be addressed, or when there is a deeper realization that the software is confusing/complex and users don’t understand how something works. It again takes a lower priority in the face of a lot of feedback and features to be worked on, or when the projects have a sense that the users will be able to find their way around their software.

User-centered approach to documentation

There isn’t a clear user-centered approach to strategizing documentation or making them accessible and discoverable. Documentation was often brought up when we talked about user and usability related topics, suggesting that projects might view a good documentation as means to make software understandable to new users (in contrast to many designers, who focus on "user-intuitive" interfaces). The most satisfying approach to documentation came from one of the projects that identified gaps in documentation when a few users, more than 1 and less than several, misunderstand how to use the software. Documentation to them, fills a usability purpose for the SROSS, but a designers perspective would suggest that good documentation is only one aspect to making a software too usable. As one project maintainer states "docs can be a filler in the usability of a platform when there’s no clear way to present some information or to completely remove the kinks in the software".
They also have introductory tutorials that are geared towards novice users and some documents that are geared towards experienced users. The most user centric approach we encountered was to use forum activities to keep the documents updated. Lack of user-centered documentation also leads to major problems in discoverability. “We document a lot but users can’t find it [easily] which is related to search and information architecture” said one of the participants who identified as a community manager.

Conclusion

It is clear from above that documentation does not take a priority parallel or next to code. Much less are its usability and discoverability a priority. Could this be owed to not defining the responsibility? Could this be a time, funding, or human behavior issue? One hypothesis explaining the lower priority of documentation is that open source (research) software projects organize around collaborating on code with other programmers. This means that non-code contributions directed to non-programmers, are seen as secondary, less motivating and less likely to garner merit in the project.
Successful projects report that documentation for them isn’t an afterthought. It is built into the development process, as and when software gets updated. Projects agree that documentation is a fall back mechanism for usability issues; it can reduce the entry barrier for users and increase software adoption. It is only justified to adopt practices that take documentation hand-in-hand with their softwares. Perhaps some projects will move out of their consistent state of WIP and finally feel caught up.

Our recommendation/s:
Prioritize documentation as much as building features: It improves software adoption and usability. Tutorials and documentations explaining features and related concepts help the community get started on the platform on their own. It saves teams their valuable time which could be better spent on more valuable areas than supporting people individually.
Adopt practices that enable projects to manage documentation: Without it becoming an added burden on the team.
Make accessibility and discoverability of documents important: Discovery is important as writing documentation itself and ensuring these documents are useful to as broad a spectrum of users as possible.
Projects can benefit from making individuals or a role responsible for documentation: This helps in cases where the project relies on contributor support.