Further improvements of documentation

[smacker]

From @dpordomingo and @mcuadros comments:

• [ ] explain better the features provided by our CLU and GUI #29 (comment),
• [x] assume no context/background in the people reading the README.md #29 (comment), -> https://github.com/src-d/code-annotation/pull/177
• [x] link to Contributing#Development from our README.md #29 (comment) -> https://github.com/src-d/code-annotation/pull/177
• [x] clearly document all ENV VARs used for configuration i.e ~~https://github.com/src-d/code-annotation/pull/36#discussion_r168110379~~ → https://github.com/src-d/code-annotation/issues/120
• [ ] provide information how to run it with DB ~~#170 (comment)~~ → https://github.com/src-d/code-annotation/issues/173
• [x] update screenshot 😋 -> https://github.com/src-d/code-annotation/pull/177

or any other not-collapsed comments in the PR https://github.com/src-d/code-annotation/pull/29

[dpordomingo]

All my comments were collapsed (I don't understand why I did wrong :( ); I'll try to list them here.

[bzz]

Added a line to description on ENV VARs.

Update: #120 was created right after

[dpordomingo]

updated issue desc with updates on .env feature

[carlosms]

About this item:

explain better the features provided by our CLU and GUI #29 (comment)

I believe the current readme has a very good introduction. Does anyone have a specific suggestion on how to improve it, or can we mark it as done?

[smacker]

original comment got collapse. So here it is:

@dpordomingo :

With the current wording, I understand the following:

UI to annotate, CLI to fetch (retrieve/download...) elements and to export. But current app offers:

GUI UI to annotate and to review the annotations, CLI to add/push/load fetch new elements to be annotated and to export the annotations made. @campoy do you think we could reword this section to clarify the features offered by our app?

But for me README is clear in current state.

[bzz]

@carlosms to speed up the review and help understanding the scope that has been addressed - could you please update the checklist in PR description?

[carlosms]

@bzz :+1:, main description is now up to date

[smacker]

Guys do you think we still need to document export in readme when we have a link in UI?

[dpordomingo]

I don't think so, it should be moved to other part of our docs (imo same reason as the one for import tool: this project is not focused in import/export databases, but in offering a web interface to annotate code and review code annotations)

[bzz]

I think it's worth to have import/export CLI documented but not in README.

As @smacker and @dpordomingo are right: we already have download for export and going to have upload for import soon, under new experiment management.

@carlosms do you think you could address this in #177 ?

[smacker]

Could anybody give me a reason why do we need CLI for import/export?

[carlosms]

@bzz:

@carlosms do you think you could address this in #177 ?

I'd rather merge #177 as it is, and do this in a future PR. If we move the CLI import and export to CONTRIBUTING, then we will want to have a screenshot or description of how to do it from the UI in the README, and the import part is not yet ready.

Let me know if you agree or if I should move import & export in #177 now.

[bzz]

I'd rather merge #177 as it is, and do

@carlosms sounds good to me

[bzz]

Could anybody give me a reason why do we need CLI for import/export?

@smacker In my option, it's just because

• we already have it, and
• that might be useful in case someone would need to use this application on their own deployment environemtn