StormSurgeLive
reorganize readme, install docs
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
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.
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
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.