📔 Improve documentation page - appearance & adding some extra instructions for clarification

[safizn]

• Reorder documentation sections and resize titles - making it easier to navigate through and introduce the repository.
• Add Operator Mono font links to the original creator.
• Add instruction notes for python installation and for docker usage.

[kiliman]

First of all @myuseringithub, thanks for taking the time to update the README. Writing documentation is not really my strong suit, and I'm sure the current README can be restructured. I was just trying to get as much information as possible in there. You should have seen the original README.

Anyway, I don't really have a preference one way of or the other on this. So you and Mark can come up with a good structure.

Thanks!

[safizn]

Sorry, I don't want to be rude, but do you really think I would go past each comment and write my opinion about ? I don't think it's worth the time I rearranged and added some instructions and links using the Github web ui, so sorry for the many commits.

It is clearly easier to read from a user perspective, as it focuses on the important parts. The header levels are nothing but a way to enlarge text and create section for easier navigation, don't treat it as some standard principle to have a single level 1 header. I thought it would be a good step in even splitting the Changelog into it's own file and linking it in the main page in the future. It's also better to just put the poll at the Thank you section or before it immediately. At the end remember that people just want to understand what is the repository for, how it does it, and how to use it for achieving the goal of improving their development setup. keep it simple and most important clear.

[kiliman]

@myuseringithub I'm sorry you didn't have a pleasant experience. I suppose that once you mentioned it, everyone suddenly had an opinion on it. The README is kind of like the front door to the project, so it's not surprising.

At least your PR has motivated us to get more organized. We've already decided that a CHANGELOG would be good and to move some of the details there.

Anyway, thanks for taking the time to help improve things. I really appreciate it.

[mskelton]

@myuseringithub My apologies as well. I didn't mean to come off as harsh as I probably did.

As @kiliman said, thank you for bringing this up as it has prompted us to think about how we can revamp the readme to be easier to use. As he mentioned, the readme is the front door to a project, so it would be good to have it looking good 😄

[amitkparekh]

@myuseringithub I am also sorry. I didn't intend to add or pile on and I apologise.

To further reiterate @kiliman and @mskelton, thank you for bringing the readme to our attention as you've definitely given us much to consider regarding improving the documentation and making the instructions as easy to use as possible.

[safizn]

😂 Don't worry about that, I don't take things personally. Just the over complication of project's contributions, having to open an issue first before writing a pull request, are unnecessary. Don't expect people to give hours of their free time discussing, whether or not to improve the instructions of a project. Thank you for this creating this tool.