Documentation and instructions enhancement.

[GioBonvi]

I was wondering for some time if there was something that could be done to make the documentation a little more user friendly, while keeping it easily accessible to everyone (non-technical users in particular).

These are some of the things I thought of and would like to hear your opinion on:

First of all, markdown files are great on GitHub, but once they are downloaded offline most users will only be able to open them in the source (not rendered) format: some users, if not most, will probably never read a file in that form.
It would be great to have some way to display documentation online and at the same time have it to work offline, but at the moment I cannot think of anything that would work like this.

Secondly the README.md file looks a little bit clogged and overwhelming to me in its current state. It could be split in different files served via Github Pages, or could be written into various Wiki pages.
As you said in my last PR the README.md file is the first thing a user sees when opening the project page: if we split up the current content into different documents or Wiki pages the file itself could be turned into a concise presentation of the project with some links to the various Wiki pages for more detailed guides/examples/explainations;

@sdias, I would love to know what your thoughts are on this matter.

[sdias]

@GioBonvi I agree with you on most points. I agree with you when you say most people won't read documentation offline, but not by the aspect of the file (raw markdown is pretty readable as is, and I even took the time to format the tables correctly to be readable when raw) but due to the files' extension (md) and the fact that Windows doesn't know that it is a text file by default and non tech savvy users don't either, so they won't even open them.

I think we should still use markdown and files to contain that information, so it isn't restricted to the website.

I like the changes that you did in your branch (splitting the files, extending certain sections) and I think that alone is sufficient to solve the second issue. Maybe we could split the customization instructions even further or restructure or rework some parts of it to be less confusing.

To solve the first issue, I think we could compile the markdown into HTML for releases. I have been using a Sublime Text plugin to do that as I edit the documentation, it shouldn't be too hard to automate that.

[GioBonvi]

Compiling markdown to HTML for releases looks like a great idea!

What do you think would be the besta way to go for online documentation? Github pages or Wiki? Both formats accept markdown files and they are quite equivalent for small projects like this, but given your proposal of compiling MD to HTML I would use Pages, so that: .md files can be part of the project (/docs folder) and remain easily accessible to be converted to HTML for releases (which would be slightly more complicated with the wiki).

[sdias]

I'm not sure what you mean by pages, but I think the best would to leave the information in MD files, with the README being the index file. That way users can easily explore all of the other MD files easily (by using the links) and we wouldn't have to tie the information to another location (which we would with a Wiki) or maintain it in another format at all. In addition to that, we could compile to HTML for releases, for offline viewing.

[GioBonvi]

GitHub offers a service called Pages: it allows you to host your documentation (.md or .html files) on a website directly from your project.

Let me explain with a practical example.
This is a project a recent project of mine: https://github.com/GioBonvi/GoogleCalendarBirthdayNotifications. If you open the link you will find nothing more than the classical GitHub project, however, since I have activated the Pages service in the project settings dcumentation files can also be accessed via this link: https://giobonvi.github.io/GoogleCalendarBirthdayNotifications/.
My project only has one page, but if there were more they would be all browsable like that. The advantage is that it offers a nice way to serve good-looking documentation, without the need for additional maintenance.

[sdias]

Neat, thanks, I didn't know that. I didn't look into it in detail, but as long as it allows us to maintain our documentation easily and couple it with the code, since the documentation is version-dependent, I'm happy with it.

[GioBonvi]

Issue closed with the merge of branch reorg-documentation.