reorganize readme, install docs

[wwlwpd]

@jasonfleming can you take some time to describe your vision?

[wwlwpd]

Hi @jasonfleming, I just wanted to follow up on this issue. I have most if not all information scattered among several files, but what I need is an idea of how to best structure the information in a unified, consistent, and complementary way with the other information. Otherwise, I feel like I am guessing what the best way. I am creating a new "documentation" milestone (might be better served as a formal "documentationm project") so that we can capture all that we want.

What I need help defining:

• main areas of documentation/overall structure
• main format of documentation
• main means of distributing documentation

The format has a lot to do with ease of maintenance, and in our case anything should be text based and easily maintained in the git repo (i.e., "as code" and be compatible with a development workflow). It should support being rendered in many different formats (HTML, PDF, etc) from the same source files using a separate set of tools for this output. Examples of documentation that separate information from presentation (to varying degrees and in NO order of preference):

• AsciiDoc - https://en.wikipedia.org/wiki/AsciiDoc
• Perl POD - https://en.wikipedia.org/wiki/Plain_Old_Documentation
• Markdown - https://en.wikipedia.org/wiki/Markdown
• LaTeX - https://en.wikipedia.org/wiki/LaTeX
• Docbook - https://en.wikipedia.org/wiki/LinuxDoc
• List of many more https://en.wikipedia.org/wiki/Comparison_of_document-markup_languages#Characteristics

[jasonfleming]

The documentation you've developed has been great ... the outlook and situation has changed a bit since we came up with this milestone, and the vision for the documentation has changed with it. Let's discuss over the phone the next time we have a chance.

[wwlwpd]

The wiki is really cool - https://github.com/jasonfleming/asgs/wiki - AND best of ALL, it's also a git repo. And if we're using markdown (or there are other options) - we can edit it via commandline and text editor! yay.

https://github.com/jasonfleming/asgs.wiki.git

[wwlwpd]

ooh supports Perl POD - https://github.com/jasonfleming/asgs/wiki/POD-test

I think having that as an option and also using markdown (pretty standard) is the right call, if we end up using the wiki as a frontend. No reason not too and would let us create a documents repo.