Restructuring read me and improving documentation

[rishubhjain]

As per discussion with @prashanthpai @harigowtham We are restructuring Readme.md file so as to keep only necessary information. We are also introducing another document: "User Guide" which will elaborate on how to use glusterd2 and explain glusterd2 configuration details.

README:

**GlusterD2 Introduction.**
Same as before.

**Documentation**
Will have 3 primary documents:
1)  Quick User guide
2)  User Guide
3) Development guide.

The user guide will contain details about Installing GD2, Configuring GD2, 
Starting/Using GD2, Known Issues, and Troubleshooting. The user guide will
 also have the architectural details that are present in the readme.md file.
The rest of the guides will remain similar except for some updations.

**Contributing**
Will have a link to development guides which will further have links to coding
 guidelines and installing from source etc.

**Copyright and License.**
Same as before.

Please feel free to suggest changes.

[atinmu]

Quick user guide vs user guide - what difference in the content makes these two documents meaningful?

[harigowtham]

@atinmu Quick user guide, will help people who know a bit of gluster to go ahead and use it. User Guide is the detailed description (not as detailed as a blog ) but the one that will be enough for user/developer to understand how to use it. Regarding the names, we can come to a better conclusion.

But the idea was to have 3 sections: User documentation, (glusterfs , glusterd, glusterd2, installation configuring using gluster as a storage) developer Documentation, (installing source, coding convention, and details about various things in gluster) Quick user guide (people aware of gluster can make use of it to create and deploy it and this section doesn't have much documentation)

[harigowtham]

@rishubhjain about the overview, we can have the same overview that is available in readme. we can explain it in detail in the new user guide section?

[harigowtham]

More about how we are approaching the way we are going to do documentation for GD2

The first readme page has to be kept simple and small to avoid causing stress to people by the huge content who come to this page. Its the developers who primarily visit github directly. users tend to go to the project docs as much as github. Docs will have a lot of content clearly explaining each thing in detail. doing the same here is not nice as it will make the procedure longer.

So for the devs/ users who are aware of gluster and were glusterd2 comes into play we have the quick user guide. they can use this to create volumes and consume them. They arent explained in detail. this is to avoid the time they will end up consuming.

The 'user guide' (a better name can be helpful for each topic) will give a clearer view of how glusterd2 goes with glusterfs and how one can install it (rpm/ binaries) and run it without the in depth understanding of the working. This will also contain the documentation to run the varies commands in gluster. and a bit of trouble shooting for the things they might come across. Known issues will also be mentioned to make them aware of it.

Developement guide, as the name says is just for developers and not users. it will talk about setting up go and getting the source code to installing it. then about code contribution, testing, troubleshooting and then a section to talk about various things that are helpful for a dev to understand the code better like translator, transaction framework and other docs

Let us know your views regarding this. we have tried to maintain the usual conventions for github docs and tried to make it clearer as possible. If you think we need to change anything let us know what has to be changed and why, so that we can opt the conclusion which is better.

[aravindavk]

We need one more section for Application developers who are primarily interested in consuming the APIs for integrating with there applications/tools.

• User documentation: glustercli based user guide for install/setup and manage gluster
• Developer documentation: For new developers who contribute to glusterd2
• API documentation: For application developers.

[rishubhjain]

@aravindavk This looks like a good idea. We will also provide a link to" API documentation" in" User documentation" in case the user wants to use APIs instead of CLI to manage gluster.

[rishubhjain]

A basic restructuring was done by @prashanthpai. Pratik was going to work on providing a better documentation for GD2, I and @harigowtham will be helping him. @pratikvmulay Any update on the documentation?