Gamification of Source Code Documentation & Contribution

[louy2]

Project description

In the talk I am your user. Why do you hate me?, Donna Benjamin talks about how open source software often possess a steep learning curve, lack documentation, and have difficulties transforming users into contributors. In the learning curve section she referred to a funny graph depicting that of some famous MMORPG games, the most cruel curve being that of EVE Online.

With some exceptions, game is probably the industry that has mastered the learning curve. One of the most engaging experience I have had with coding is wrapped in a Japanese game developed by an IT recruitment company called Paiza. Other examples include LeetCode, Codewars, etc.

The way games ease the learning curve is through more granular division of basic operations and immediate feedback on success and failure. When it comes to contributing to an open source project, it doesn't look good on both front. The most basic operation of contribution is down to creating an issue, but then goes right into the whole code base, be it a feature, or a piece of documentation.

Documentations is a good start point towards a more granular coding experience. For non-programmers, other than reporting bugs and requesting features, they are most ready in adding documentations, especially from a user's perspective that's different from a developer's. For novice programmers, writing documentation introduces them to the codebase. In all situations, documentation is easier and serves as a faster feedback than a bug fix or a feature patch.

On top of documentation, the code base need to be broken down into smaller pieces. The important thing to remember is that the code base is not modular, no matter how modular it is designed to be, to someone who don't know about program architecture. The way of breaking down the code base is dependent on the language, but as a first step it is useful to identify all functions (methods). The pieces then need to be ranked by their difficulty, which can be determined roughly by their length (number of lines).

The immediate feedback part is probably the easier part during gamification. A popup of congrats should accompany the finish of a documentation string. Accumulation of difficulty points on the condition of successful merge can serve as a mid-term motivation. In the end, a log of resulting commits and contributions is what hopefully satisfies the players in the long run, as well as their improved knowledge.

Because the game wants to facilitate contribution, it needs to interface directly with online source control utilities to utilize features such as pull requests. From the project's standpoint, the game may also serve as an education tool about best practices regarding sending pull requests.

Relevant Technology

Accessibility: Web related techs Source code analysis techs (probably language specific) Source control interfaces

Who is this for

The first prototype would probably be more an assistance tool for motivating experienced developers to write more documentations. Then I hope it expand to novice level programmers and non-programmers.

---

Share on Twitter/other social media if you will. Something like

New project on Open Source Ideas Initiative: Make Doc Game – https://github.com/mikaelbr/open-source-ideas/issues/32

[ahopkins]

Interesting idea. So, are you thinking of providing a web based platform for documenting an existing repository? And, possibly also provide the documentation output? Sort of a Stackoverflow meets GitHub meets Read the docs? If so, count me in.

[louy2]

@ahopkins Exactly! Unfortunately I don't have a project to "count you in". I have been thinking about it and found here so I dumped it out. I am not confident at all to start such a project. Please feel free to adopt it.

[ahopkins]

@louy2 I am definitely liking this idea and have some ideas on how to build, etc. It also seems like you have some good ideas and vision on the end game solution and what it would look like. Are you wanting to partner up to take this on, if nothing else for strategy?

I started a new repository (https://github.com/ahopkins/devdocs nothing pushed yet) and hope to start in the coming days/weeks filling in some issues and getting the basics together. First orders of business are to sort of map out what the simple user experience will be. What are the motivations, how to get people involved, etc. Certainly needs a much better name.

[Haroenv]

Ant-design/ant-design has this: https://getbadges.io/

[georoot]

@ahopkins from what i understand is having a gamified approch for documenting stuff. SO already have implemented something similar in a more broad sense with documentation but they are more lanaguage specific. Having something against individual projects is a nice addon. Additionally we can link this to github profiles and projects, something like gitter to maintain docs for all projects on github. using devdocs might not be such a good idea as i know of an already existing site that provides offline documentation with same name. Let me know if you are cool with django and further need help to startup the project 👍

[ahopkins]

@georoot Its a temp name until something better comes along. My initial thought was to run with it in Django. If you want to join in, I'd love to have you. I have some ideas in my head already for the UI and architecture.

[georoot]

@ahopkins just had a quick look at the repo from what it seems is you want to create an api on django and a SPA for UI, a better idea is to have 2 separate repo for them as they are not related. Grunt/gulp could be used for UI dev and lets keep django with DRF for developing api :) I was a little busy over sunday but yeah now i can help you with contributions. Also create a gitter chat room for faster collaboration (y)

[ahopkins]

@georoot let's continue the conversation here: https://gitter.im/skemdocs/Lobby

[shabadsobti]

@ahopkins Are you still working on this? I would love to contribute to this idea.

[KOLANICH]

The important thing to remember is that the code base is not modular, no matter how modular it is designed to be, to someone who don't know about program architecture.

This is the main problem. Lot lot of projects have Doxygen docs but don't have high-level docs describing the architecture and design decisions. And even if they have, these docs are often obsolete.

[louy2]

I now have even less time to contribute than when I dumped my thought above, but if I am to approach this problem today, I think the first step I am going to take is to find a Rust project and design a game specifically around it, and go on to try to generalize the design to most Rust projects. I pick Rust for the following reasons:

1. Rust has a fascinating documentation generator included in the standard distribution of the language, and the community actively rallies around documentation with such projects like Docs.rs.
2. Rust has a easy to use and enforced module system which eases the problem of opaqueness of architecture common in other languages, emphasized by @KOLANICH . The documentation generator cooperates with the module system to bring the modular structure of code to the documentation.
3. Should any more complicated language analysis needs arise, Rust offers nice and growing language analysis capabilities with syn.

Thinking more about the idea, there are many more blocks on the road to good documentation than opaqueness and lack of motivation. To know enough about some code to document one must first experiment with it, and explore its functions, features, interactions, finally down to idiosyncrasies. But for many popular projects, even building them and running the basic examples is quite a hassle for ordinary participants. This is another reason I prefer Rust, which has cargo as its build tool and projects can almost always be built just with cargo build.

TLDR: Such a game in fact requires a great documentation story from the community it serves. It needs:

1. easy to use documentation tools
2. a codebase that's easy to build and explore
3. preferably a good module system to help generate documentation tasks
4. preferably good language analysis libraries to help generate documentation tasks

Rust is my preference, but any project that has 1 and 2 above is hopeful in my opinion. I'd pick Python, Ruby or Java as the followups, for they are the better documented ones in mainstream languages. Clojure and Haskell fit the bill even better, although their communities are more of a niche, but if any lambda fan from there like this idea, I'd be more than honored and excited to see what you can make of this.

[KOLANICH]

Rust has a easy to use and enforced module system which eases the problem of opaqueness of architecture common in other languages, emphasized by @KOLANICH .

It doesn't solve the problem. Even self-documented code has a fatal flaw: a dev has to reverse-engineer developers' intents, vision and ideas from the code and guess why that way has been prefered over alternative ones. And reverse-engineering open-source software docs is not fun.

[louy2]

And reverse-engineering open-source software docs is not fun.

I totally agree with you. But the goal for such a project is not to make every documentation effort fun. The key to a good software effort is always down to the people, and if there's some dilapidated software out there with shitty documentation, such a project would not help much. Consider such a project more an outreach effort for a decent project instead of a lifeline for under-maintained ones.

[ahopkins]

I still think there is a need for this, and I still think this is a good idea. I have a bit much on my plate right now. @shabad If you want to message me offline I can let you know a little more where this ended up.

[ahopkins]

@louy2 +1 for Python (as a core dev here, I am a bit biased though). But Rust is also a good choice.