-
Notifications
You must be signed in to change notification settings - Fork 47
How to add config examples to generated feature docs
To provide example configurations that users commonly need and can therefore copy/paste from this topic. The text around an example explains what's happening in the example so that the reader can understand it.
The Examples section should be a task topic. If there is a valid need for a procedure to be documented, raise a new issue with as much information as you have about why it's necessary and that can then be prioritized separately. The Examples section should only be example configuration and and an explanation of what it shows.
To create an Examples section for a page, complete the following steps.
-
Create a folder in the
modules/reference/pages/feature/directory with the same name as the feature (for example,modules/reference/pages/feature/federatedRegistry). -
In that folder, create an examples file named
examples.adoc. You can also include an optionaldescription.adocfile that provides an extended description after the generated first sentence in the topic. For example: https://github.com/OpenLiberty/docs/blob/vNext/modules/reference/pages/feature/jdbc/examples.adoc is included by the gen doc that builds the JDBC feature doc -
In the rare case that you need to create an example or description that is only valid for certain versions of a feature, include the feature version in the name of the folder, for example
modules/reference/pages/feature/federatedRegistry-1.0/examples.adoc. If you need to create an example that is valid for multiple, but not all, versions of a feature, you must create a separate folder andexamples.adocfile for each version of the feature where you want the example to appear. If an example only applies from a certain version forward, the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, egmpOpenAPI-3.2. At the time of this writing, the only feature this applies to ismpOpenAPI 2.0and later.
The .gendoc files are generated from properties files in the Liberty runtime build. For example, here's the Social Login feature's source file. Any edits to the generated description of a feature must be made in a PR to this repo and approved by the Open Liberty development team.
Start by identifying which are the most important/likely/common config examples that a user might need. Put the examples in order of likelihood of being needed. Make sure they (and especially the first example) are as simple as possible; the minimal config needed to make each thing work.
Put each in a separate sub-section with a heading that clearly states what the config provides. Then give a brief explanation of why you might need the config and/or what it provides. You don't need to provide instructions in the text about what attributes to set because that's clear from the example provided; instead focus on explaining what the key parts of the config shows/provides (like we do in the guides).
You can link to the relevant concept topics and/or other config topics where needed, if necessary.
In general, keep the config snippets:
- Useful - don't just include everything. Ideally, max 2-3 examples only. Don't get caught up providing config for edge cases.
- Short - do not include the whole server.xml or other elements/attributes that do not contribute to the example being described.
- Focused - just demonstrate one thing at once (as much as possible) so that users can mix and match the examples easily and can see exactly what is and isn't required to implement something. eg don't include all the security or logging elements that you would in reality use in a full server.xml - they just obscure what's necessary for the particular feature (eg social login).
- Relevant - focus on supporting the cloud-native microservices (not traditional app server deployments).
- Production-ready - demonstrate example config that users can use in real apps. If it's useful to demonstrate non-production code, clearly state why and when it's useful and should be used (eg specific benefit to developers at development time).
Avoid being instructional: these are config examples with descriptions about what they show and what you get from using them. Provide clear descriptions of what the example config shows before each snippet. Make it clear when it's useful and why you'd use it. Link to relevant Open Liberty topics and guides where appropriate.
Ultimately, make sure that the Examples section is useful to the target reader in the most common scenarios.
If a user must enable multiple features for a particular configuration example to work, use the following format to explain. In this example, write the feature names in plain text (not monospaced):
To enable this configuration, in addition to enabling the x feature, you must also enable the y feature and the z feature in your server.xml file:
For an example, see the Viewing and validating Cloudant databases section of the Cloudant Integration feature doc.
- Make sure each example has a descriptive heading that explains the user goal that is accomplished by the code in the example.
- Be as specific as possible while keeping the headings concise
- Use short declarative phrases for the headings. Do not use gerunds or noun phrases.
- Make sure headings on the same page are parallel (If you follow the previous bullet point they will be).
See the LDAP User Registry feature for relevant examples
The first sentence (usually just the one) of the topic is set in the feature's properties file (in the runtime build). If you think it could be worded better, do a PR to the properties file. However, if you think the feature could be better described in a longer form, you can optionally add a paragraph of 'extended description' in a similar way as for the examples (https://github.com/lauracowen/docs/blob/sociallogin/ref/feature/description/socialLogin.description)
In addition to the preceding guidance, edit your code examples to consider the following guidelines, which are intended to support both clarity and consistency among the examples. If you make any substantial changes to a code example, make sure to send it back to the SME for review.
- Don't include a
<featureManager>…</featureManager>section in the examples. The enabling config is already autogenerated at the top of every feature page - Make sure any products, libraries, services, encodings, browsers, etc. in an example are current and reflect current practices. Eg. an example that refers to Internet Explorer 10 probably needs to be updated for Chrome. Work with SME to ensure examples are up-to-date
- Don't use comment lines in the code to explain what's happening in the example. Instead, put any necessary explanations in the text introduction before and after the example. Ideally, before the example, explain what it shows overall. If more explanation of the config is needed, add another paragraph after the example to break it down.
- Don't use variables (eg for values or for file paths). Just provide plausible example values and then describe what they represent in the explanation of the example config. The exception being any variable that is defined by the server configuration. For example, instead of
:${server.config.dir}, which can be specified directly in the server.xml file and the runtime will supply the appropriate directory. - In text descriptions, don't use triangular brackets around element names. Eg. say "the
requestTiming element" instead of "the<requestTiming>element" - The source highlighting of the code examples needs to show color - for server configuration examples, specify that it's XML in the source. In your adoc file, add [source,xml] tags above the opening ---- tagging. If the code is, say, Java, you'd put java instead of xml, and so on.
- Whenever possible, put a closing slash in the opening tag in each line instead of having a separate closing tag. eg . This may not be possible for complex element config or multi-nested elements that require more than one line for a readable example.