JSON API – use cases
sergey-alekseev opened this issue · 3 comments
Use cases:
1. In the text editor (Sublime Text 2)
Actor: A Ruby programmer
Action: looks into someone else's code and finds an unfamiliar method.
Goal: He wants to browse this method's documentation.
Solution: He uses a plugin through a keyboard shortcut and instantly gets a documentation in a separate tab. He gets a link to RubyDocs.org HTML documentation as well.
Advantages: Getting the current Ruby version implicitly, based on .ruby-version file, .rvmrc file, etc. Quick and easy access to documentation while staying in "the zone".
Similar: https://github.com/kemayo/sublime-text-2-goto-documentation. Disadvantages: Not working with Ruby on Rails. Opens a browser.
2. In the group chat (HipChat)
Actor: A Ruby programmer
Action: chats with a Ruby team lead about a refactoring issue.
Goal: He wants to get a description of some class in order to address recent team lead's tips.
Solution: He asks a team's chat robot about a description of some class and instantly gets a documentation in an answer.
Advantages: Quick and easy access to documentation while staying in "the zone".
Similar: https://github.com/sergey-alekseev/lita-answers.
@manuelmeurer do you like it?
Please, let me know if I could proceed with an implementation issue.
It's definitely a good idea! Do you plan to write the Sublime Text and HipChat plugins as well?
I want to avoid adding features that may not be used in the end.
How would you generated and store the documentation bits?
Currently the HTML docs are generated on the server and then synced to S3.
How would the API for receiving the docs look like?
Glad that you like this idea! Sure, I plan to write the Sublime Text 2 and HipChat plugins as well.
I understand you and I'm going to introduce useful features only.
See #3 for implementation details.