Gamification of Source Code Documentation & Contribution about ideas

[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.

[Haroenv]

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

[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.

[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.

[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.