Documentation improvements

[fmachado]

Current problem
At some point after the release of version 2.3 of this library, changelog and description of new features were frequently added to the README.md file. With more and more features being added, this file went from quickly showing what this project can do to a full documentation with 22 topics and there is not even a "Table of Contents" to help with navigation.

Proposed solution
I would like to suggest we move everything to a new location except:

• Project description including version and build status;
• A quick "how to use this library" with a few lines of code (does not need to be production grade code);
• A link to the complete documentation;
• How to contribute.

If you liked this idea, please vote with a 👍 here!

Wiki vs. big .md file
IMHO the best place for a more detailed documentation would be the "Wiki", currently enabled for this project. Unfortunately this Wiki does not allow edits from non-developers and would require InfluxData to change this configuration.

Here are the options I can identify:

1. Use a big .md file

• Pros: anyone can contribute; single place with all documentation; easy to search for keywords (CTRL+F is enough).
• Cons: Painful to navigate

2. Use multiple .md files

• Pros: anyone can contribute; smaller files with specific content.
• Cons: Difficult (if not impossible) to link one file to another; difficult to search for keywords (GitHub search bar is the only option).

3. Use Wiki

• Pros: smaller pages with specific content; easy to navigate;
• Cons: difficult to search for keywords (GitHub search bar is the only option); can only be edited by InfluxData developers (i.e. part of the GitHub InfluxData team).

So, what do you think?

[majst01]

👍 for this effort, i also vote 1.

[fmachado]

Hi everyone,

I've submitted a PR #665 containing the new README.md and moved the previous content to MANUAL.md.

What I did?

• followed the basic recommendations from https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
• used a similar way to document the project as the new influxdb-client-java library;
• added links to InfluxDB documentation;
• reduced to one simple example on how to use the library.

I'll continue improving the MANUAL.md file later.

Please, review this new version and check for typos or grammar mistakes: English is not my first language and I'll be more than happy to have your help.

[majst01]

Hi @fmachado
I think we can close this issue, thanks for you effort !

[fmachado]

Continuing with our efforts to improve the documentation, I'm now working on MANUAL.md.

With PR #669 , my idea was to document the important aspects of this library around the initial example, shown on README.md .

This is still a "work in progress" task and I'm planning to finish it during the next days.

Feel free to comment or suggest improvements directly on PR #669 .