search

ds300 / jetzt

Speed reader extension for chrome
Other
486 stars 124 forks source link

Document where the main algorithm is implemented and how it works #144

Open ian-kelling opened 10 years ago

ian-kelling commented 10 years ago

I've been recently been working on a similar project for emacs, https://github.com/ian-kelling/spray.

Based on a quick count, similar programs are implemented in 6 languages, 9 platforms and 11+ projects. Every one has a similar algorithm to choose a word, an accent character and an interval to display it. How to do that best is quite important. However, how each project does it is generally buried in unrelated code, and mostly undocumented. It is prohibitively time consuming to figure out the algorithm and differences between them for each project. This sucks. Users would like to know so they can pick one. Developers would like to know so they can get ideas and spread improvements among different projects.

A few minutes of work from each project's maintainer can fix this. Please document which file(s) and function(s) implement the main algorithm, and preferably how it works in plain english or pseudocode. An example for the my own project is at: https://github.com/ian-kelling/spray#algorithm-details.

clin045 commented 10 years ago

Better documentation is something I'd like to see too. I've wanted to contribute to jetzt because I think it's a great project, but I haven't been able to understand large portions of undocumented code.