search

HabitRPG / habitica

A habit tracker app which treats your goals like a Role Playing Game.
https://habitica.com
Other
11.82k stars 4.05k forks source link

Generating Documentation for Devs and Designers #1318

Closed AndreCaseyScott closed 8 years ago

AndreCaseyScott commented 11 years ago

Documentation and Styleguides

I've been hearing a lot about styleguides as way for teams to better organize and make sense of their code. Given the nature of OpenSource Projects and Github, having a way to generate styleguides for use by the developers and designers would be a great way of "onboarding" [to reference gamification] new folks, and making debugging easier for existing folks.

Personal Thoughts on this

Right now, my "list of Shame" is pretty long, but javascript is at the top of it. I can pick it apart [slowly], but generally have no idea where to start. CSS I am proficient with, but struggle to locate the files where classes and styles are housed while debugging.

Thus I see creating documentation as a way to enable me to help out more, since my time is limited, and I definitely don't spend enough time day-to-day with it to instantly know what does what. My hunch is that it would make hunting down front-end bugs faster, and easier for folks to contribute without a huge investment of time to get to know the code.

Awesome! What would we use?

The two projects that sound most promising [given that HabitRPG is Node.js based] are:

They all use Markdown, which is the most portable format to use for documenting.

Though other suggestions are encouraged.

Cool! What next?

Luckily, the configuration for both Docco and StyleDocco is minimal. Every once and a while a dev or dsgnr would run all the JS and CSS files through them to generate HTML docs of all the comments in the code. This is done locally with Node and the resulting documentation would be uploaded to Github.

The only real "hard work" would be adding comments to each section of the code. This is already being done to some degree, but more thorough comments would be helpful for new folks just jumping into contributing to HabitRPG. Adding some Markdown for styling would help organize the resulting HTML docs.

I have a selfish interest in fleshing out any documentation, as I would be learning Javascript as I go along, as well as making it easier to contribute to HabitRPG. Though I won't be able to dive into this too much for a few weeks myself.

Also wanted to gauge the interest of contributing devs and dsgnrs to date as to whether you would actually use something like this.

tag! you're it

@lefnire @litenull @zakkain @Shaners @switz @SlappyBag @fragmental

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

AndreCaseyScott commented 10 years ago

I realize I should be discussing more of this here instead of pull requests... latest thoughts at #1583 , but plan to write-out-loud here soon.

AndreCaseyScott commented 10 years ago

Still unsure of what framework to use. Markdown files would be the most portable files, as they can be parsed easily to HTML or any other format.

So far options are:

I'm really attracted to the Daux.io option. Less configuration than either GHPages or Wintersmith. Plus a lot of nice extras like a "fork on github" ribbon, Google Analytics, and Twitter links. I'll test it soon, to see if it's viable.

librarianmage commented 8 years ago

What is the progress on this?

Alys commented 8 years ago

I'm going to close this since we haven't commented on it in ages but if other admins want to reopen, feel free!

Lately, Habitica has been using lint to enforce code style and consistency, and we're developing a new, more consistent API which will have more thorough documentation. The code base is being improved and standardised, which will help programmers understand it better, and we're improving our wiki documentation.