Create a simple README.md #16
Conversation
Now that we have a user guide, the README can be much simpler and reference the user guide for details.
README.md
Outdated
|
|
||
| * Create a GCP VM to act as a [control node](/docs/toolkit-user-guide#control-node-requirements); it should be on a VPC that has SSH access to the database hosts. |
There was a problem hiding this comment.
Because these steps generally need to occur in order, I'd use a numbered list instead of a bulleted list.
In Markdown, just precede each step with "1. " For example,
1.
1.
1.
There was a problem hiding this comment.
Actually I can't make numbered lists work; we have embedded examples, and markdown numbered lists must be contiguous.
There was a problem hiding this comment.
I think if you indent the examples two or three spaces, they are recognized as a continuation of the step or bullet item. At least that's the way it works for the Markdown we use on cloud.google.com.
If you indent them 4 spaces, they should get interpreted as a code block. At least if you're writing for cloud.google.com. The "```" flag makes it so you don't have to worry about indentation.
There was a problem hiding this comment.
That's the issue with numbered lists: indentation becomes mandatory. Anyways, I've added a ton of indentation for all the examples so that the lists do number now.
Use official product names as suggested by bpj146
README.md
Outdated
|
|
||
| * Create a Google Cloud VM to act as a [control node](/docs/toolkit-user-guide#control-node-requirements); it should be on a VPC that has SSH access to the database hosts. | ||
| * [Extract the toolkit code](/docs/toolkit-user-guide#installing-the-toolkit) on the control node. | ||
| * Create a Cloud Storage bucket to host Oracle software images. [Download software](/docs/toolkit-user-guide#downloading-and-staging-the-oracle-software) from Oracle and populate the bucket. Use [check-swlib.sh](/docs/toolkit-user-guide#validating-media) to determine which files are required for your desired Oracle version. |
There was a problem hiding this comment.
I'd pull out the Download software and check-swlib.sh sentences and make them a separate step after the gsutil command example
There was a problem hiding this comment.
In this example, check-swlib isn't a step. If a user doesn't know which files to download, they can run check-swlib to tell them.
|
|
||
| ## Oracle Software Installation Steps ## |
There was a problem hiding this comment.
Rachel had suggested that Simon review the sections in the old README that suggest tasks both for currency and to make sure they're covered in the user guide. For example, for the following, we might have the parms listed in the user guide for some of the following, but not the actual procedure steps:
- Host Setup Steps
- Oracle software installation steps
- Database creation and configuration
- Execution instructions
There was a problem hiding this comment.
I think the some of the internal structure is worth documentation (though it's already out of date), but not necessarily in the readme. A user guide section or a file in /docs/ would be fine I think.
Regrettably github's editor doesn't do live spell checks.
…rketplace, RHEL7 and OEL7 dev/oratk-26 (google#18) * Small formatting udpates * Revert "Small formatting udpates" This reverts commit 20c1983d049df0930190c87f380f9af7cbfe19af. * Add Gabriel's changes to dev/ branch * Revert "Add Gabriel's changes to dev/ branch" This reverts commit 9888dfe745017424b4c0218190d8940d9d3a0615. * Modifying conditions for additional packages reuirements on RHEL7 Marketplace, RHEL7 and OEL7 (google#16) * Small formatting changes, only to blocks updated by Gabriel --------- Co-authored-by: Simon Pane <pane@pythian.com>
Now that we have a user guide, the README can be much simpler and reference the user guide for details.