first cut at docs re-org #680
Conversation
site/model.md
Outdated
| - [Model Semantics](#model-semantics) | ||
| - [Declaring Named MBeans to Delete](#declaring-named-mbeans-to-delete) | ||
| - [Using Multiple Models](#using-multiple-models) | ||
| - [The Archive File](site/archive.md) |
There was a problem hiding this comment.
Breaking the model section into a separate file really improves the top-level page a lot.
"The Archive File" link seems a little buried here now. Anybody else think it should be linked to the top page instead, maybe under "Concepts" on the top page?
There was a problem hiding this comment.
I agree with you, it is hard to find stuck under models.
There was a problem hiding this comment.
I agree. If the Archive File information needs greater visibility, then we should move its cross-reference to the Home page under Concepts.
| @@ -56,346 +15,25 @@ Currently, the project provides several single-purpose tools, all exposed as she | |||
| - The [Compare Model Tool](site/compare.md) (`compareModel`) compares two model files. | |||
| - The [Prepare Model Tool](site/prepare.md) (`prepareModel`) prepare model files for deploying to WebLogic Kubernetes Operator environment. | |||
| - The [Extract Domain Resource Tool](site/kubernetes.md) (`extractDomainResource`) generates a domain resource YAML for use with the Oracle WebLogic Server Kubernetes Operator. | |||
| - The [Model Help Tool](site/model_help.md) (`modelHelp.sh`) provides information about the folders and attributes that are valid for sections and folders of a domain model. | |||
|
|
|||
| As new use cases are discovered, new tools will likely be added to cover those operations but all will use the metadata model to describe what needs to be done. | |||
There was a problem hiding this comment.
the variable injector tool also a "tool". should it be under this section?
There was a problem hiding this comment.
If so, then yes, it should be listed here.
There was a problem hiding this comment.
There's some confusion here (not new) as the page for "Variable Injector Tool" (site/variable_injection.md) is also the page for "Variable Injection" under "Tool Configuration". We could link that page from both places for now, but long-term, I think it should be split into two topics, the stand-alone tool and the configuration. The configuration is relevant for Discover, Variable Injector Tool, and Prepare Model Tool.
There was a problem hiding this comment.
If we link here, we could just use the intro sentence from that page:
"The Variable Injector Tool is used to tokenize a model with variables."
site/model.md
Outdated
| - [Model Semantics](#model-semantics) | ||
| - [Declaring Named MBeans to Delete](#declaring-named-mbeans-to-delete) | ||
| - [Using Multiple Models](#using-multiple-models) | ||
| - [The Archive File](site/archive.md) |
There was a problem hiding this comment.
I agree with you, it is hard to find stuck under models.
|
So far, I'm in accord with all the suggestions provided. Here's a question for you. Do you think I should consolidate the text from some or all of the Model Use Cases pages (into the new model.md file) and the Tool Configuration pages (into the new tool_configuration.md file). It's ok to to put some of them together and link to the others if the consolidation makes the index file too long. What do you think? |
There was a problem hiding this comment.
I agree with merging the Tool Configuration pages into the new tool_configuration.md file.
They are mostly pretty small, and there's some overlap in the discussion of Custom Configurations.
But the [Variable Injection] link there might have to stay a separate page, until we get it separated out for the tool vs. configuration.
There was a problem hiding this comment.
For the first case, did you mean consolidate the text from some or all of the Model Use Cases pages into the new use_cases.md file?
That makes sense to me. Those aren't very big, and there is some overlap there in discussing using Model Help tool for those.
model.md is already big, and doesn't seem to be a good fit.
|
YES, my mistake, sorry. I meant "consolidate the text from some or all of the Model Use Cases pages into the new use_cases.md file." |
site/model.md
Outdated
| ... | ||
| ``` | ||
|
|
||
| This feature does not apply to named security providers within a realm. These items follow a special set of rules that are required to maintain their ordering. See [Modeling Security Providers](site/security_providers.md) for detailed information. |
There was a problem hiding this comment.
Link is broken, remove site/ prefix.
Check for others in this file ?
New files have some also, but they are getting re-organized
There was a problem hiding this comment.
I will definitely finalize the links after I get the final OK (from Derek) for this re-org, if he likes it. Thanks for pointing it out.
|
ok. I will fix all the links and make the changes requested by Richard and Carolyn before re-submitting this request.submitting. Thanks. |
|
To all, please re-review the second pass docs re-org. I took Richard's and Carolyn's suggestions for content placement. I think I fixed all the links, but I am unsure about the proper syntax for linking to a file.md#anchor_name. For example, I used this syntax, model.md#simple-example. However, elsewhere, I thought I saw this syntax, model/#simple-example. If my choice is incorrect, please let me know and I'll fix it throughout. |
This is a preliminary revision. Something we can discuss or a basis for further work, if you like it. What I think is good: the home page/main README file (slimmed down, limited to information that first time users would want to know), the Concepts section, Model doc (seems complete). The other two concepts docs (Model Use Cases and Tool Configuration) right now have only cross-refs to their material. I'd have to look at each individual sub-topic doc but my suggestion would be to bring most of the content from the sub-sections into the main concept doc.