hamhpc
commented
6 years ago To expand on the Installation Setup Guide structure further... the initial front page to the Setup Guide (index.md) would take on a standard format like say an overview and then the general process for installing this stack. It would be platform independent. This is because we want this to appear fairly straight forward and easy but yet be able to show the details on what's needed for all the different platform installs we want to cover. I mean after all, the process is the same:
- obtain a host
- create an account (islandora) that can install and run software
- prepare the host to run docker
- docker commands to build and start the stack
Then you move off to installing test data, starting new, or migrating data.
I'm a little worried with so many options that it could appear more a complicated process than it is.
This generalized formatted index.md document would then be copied and used for detailing the other platform installs by filling in the details needed for that platform. The main index.md will also have the full list of links to the other install options at the end of the page (Centos, MacOS, etc). This way we keep a similar format and people see it still flows the same way in terms of the install process. If someone wants to create a new method for a different platform they can grab the base index.md page to start with.
Anyhow.. just a brainstorm here... trying to distill down lots of different options into something that could be easier to work with. Overall a lot to process yet so I'm sure I'll have more thoughts on this while I sort more of it out. Nice work overall!!!!
g7morris
I'm going over the documentation to start some testing. Looking at section 1.4 I am wondering if this can get refactored into something like the following:
1.4 - Installation (previously called Testing but it seems strange to test something if we haven't installed anything yet =)).
Now instead of having all the documents in this 1_4 directory I propose to create a sub directory called 1.4.1_Setup_Guide. Then it would have an index.md for the first page and general info. This page would also specify the other different methods to install this stack. There would be a centos.md, ubuntu.md, ansible.md and so on in this directory. The idea here is that someone could potentially add a new method to this install but not really change the format of the documentation and prevent the main TOC from getting so large with lots of options. We would just go to index.md and add this new method as another link on the main index.md page.
The next section would be 1.4.2-New-Site and contain the new site install instructions.
The next section would be 1.4.3-Test-Site and contain how to install sample data.
The next section would be 1.4.4-Migration guide and again this would become another sub-directory that has an index.md for the basic/common information and then sub pages like centos.md, ubuntu.md, ansible.md etc. Again allowing someone to write a specific migration guide and add it as another page in this section.
As for the Dev Build pages I suspect they should be moved to the section 3 - developer guide? I'm not sure on this one.
Lastly you would have a 1.5 being a Testing section and moving 1.5 Alphas to 1.6 Alphas. I think this would certainly help with the flow of the document and keep choices down to a minimum as well as having to repeat a lot of information on each types of pages.