-
Notifications
You must be signed in to change notification settings - Fork 55
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.
We're putting the example config in these generated feature docs to avoid duplication in reference docs for OL. In KC, often manual duplication of generated reference docs, which then needed manually maintaining. An additional benefit is that the generated feature docs are not that useful in themselves so by inserting an additional Examples section we're making them more useful.
The Examples section we're adding to the generated feature doc is not however meant to 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 config and what it shows.
In the source on GitHub, there is a 'gen' folder containing .gendoc files which contain the basic generated page.
To create an Examples section for a page, create a folder with the same name as the feature (e.g., federatedRegistry). Then, in the folder the examples file is named examples.adoc. You can also include an optional description.adoc file which provides an extended description after the generated first sentence in the topic.
For example: https://github.com/OpenLiberty/docs/blob/master/ref/feature/jdbc/examples.adoc is included by the gen doc that builds the JDBC feature doc
The .gendoc files are generated from properties files in the Liberty runtime build. For example, here's the Social Login feature's source file.
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).
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.
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.
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. For example, instead of
uri="file:${server.config.dir}/hazelcast/hazelcast.xml ", useuri="file:server1/hazelcast/hazelcast.xml". Watch out for the dollar sign and curly brackets ${}, which indicate a variable. - In text descriptions, don't use triangular brackets around element names. Eg. say "the requestTiming element" instead of "the 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.