How to write conceptual introduction topics

Aim

To provide an introduction to an Open Liberty concept/technology that is important for the target audience to understand to help them be productive.

We're not trying to document everything; just what's important to the majority of the target audience (in the context of developing and deploying cloud-native microservices/web services).

Writing style

Often, the following questions can only be answered in discussion with the SMEs:

• Who the topic is aimed at? Address the relevant persona (eg app developer, ops/admin) in relevant language with an understanding of what they're already likely to know or not know.
• What real problems can the target audience use this tech to solve? What will they achieve by reading this topic?
• What are the most common use cases (scenarios) in which the target audience is likely to use this tech?
• How will they use it? (if it's about a programming concept, provide example code; if it requires procedural instructions, create and link to a separate task topic)
• If it's about a technology that's not specific to Open Liberty, define the technology/concept succinctly but don't go into great detail about how it works. The reader can find that information elsewhere (find a good location and link to it). Focus here on how it is in Open Liberty (if relevant).
• Link to common config examples in the relevant feature docs (see How to add config examples to autogen feature docs). Don't include config info here (if configuration is more complex than just a couple of examples, provide a separate task topic of the procedure).
• As relevant (if it provides value), link to specific Javadoc, other topics, guides.

Examples

• Concurrency in microservices
• Development mode