Skip to content

Documenting Open Liberty

Jump to bottom
David Mueller edited this page Jul 18, 2023 · 21 revisions

When you change something external in the Open Liberty runtime that affects the user's experience of Open Liberty, request new or updated information about the affected part of the runtime. All Open Liberty information is published on the Open Liberty website:

Where should my runtime change be documented?

All runtime updates that users experience must be announced in the release blog posts. Beyond that, the requirements for documentation vary according to what your runtime update is and how that area of the runtime has been documented so far.

Go through each of the following questions to see what new or updated information you should provide:

  1. Release blog posts: What does the target user need to know about your runtime update when it's announced for the beta and GA releases?

    For the beta release blog post, raise an issue on the open-liberty backlog. For this post to be included in the beta issue please make sure that this is completed by the end of Friday following the GM (Tuesday).

    For the GA release blog post, raise an issue on the open-liberty backlog. For this post to be included in the GA issue please make sure that this is completed by the end of Friday following the GM (Tuesday).

  2. Standalone blog posts: Is there more you'd like to say about your runtime update than will fit in the release blog post?

    Optionally, write a standalone blog post about your new runtime update (eg Pre-populating database connections for better response times in the cloud, JAX-RS and Open Liberty: BYO Jackson). This should not try to replace having information in the Open Liberty docs; instead it should take the user through a simple scenario from start to finish so that they can see a common way to be productive with the update. The dev advocacy team can then promote your post on social media etc. You will also need to contribute documentation to the Open Liberty docs (see Steps 5 & 6) so it's up to you if you want to promote your update through a blog post as well.

    To write a standalone blog post, follow the instructions in the blogs repo.

  3. Guides updates: Does an existing guide need updating?

    If so, raise an issue on the guides backlog.

  4. Guides new: Should you contribute a new guide? Do the Guides team need to consider developing a new guide?

    If so, raise an issue on the guides backlog.

    Consider whether the runtime update is significant to the target user's experience and whether it's something we should promote as relevant to developing and deploying cloud-native Java microservices. If you propose a new guide, and your proposal is accepted, it will be prioritised for development and discussed further with you.

  5. Open Liberty docs updates: Does the docs team need to update the existing topics in the Open Liberty docs about this area of the Open Liberty runtime?

    If so, raise an issue on the docs backlog.

    In the issue:

    • What do 80% of target users need to know to be most easily productive using your runtime update?
    • Which release will the runtime updates target? The Open Liberty docs team will aim to get the docs updates published in sync with the runtime updates.

  6. Open Liberty docs new: Does the docs team need to write new topics in the Open Liberty docs?

    If so, raise an issue on the docs backlog.

    Consider whether the target user of your runtime update would need help to know how to use it, and whether the existing Open Liberty docs are sufficient or not. While blog posts can be a stop-gap if the docs can't be ready in sync with the release, anything that's important for most target users to use your runtime change must be also included in the docs.

    In the issue:

    • Provide the information that a user would need to use the runtime feature and why they would need it (give some example scenarios). The docs team will define the specific topics to be written and the structure of those topics in the navigation.
    • If foundational topics do not already exist about your runtime area, provide the docs team with the basic information that target users would need to know in order to understand the new info.
    • Which release will the runtime updates target? All new information in the Open Liberty docs must be added in the context of foundational topics that introduce that area. This is so that the published docs are coherent to the user even if they've not used Open Liberty before. If there are already foundational topics, the docs team will aim to complete your updates in sync with the runtime release. If there are not already foundational topics, they might not be able to complete all the work in sync with your runtime updates, but make sure that all the information is recorded in the issue so that it's not lost.

  7. Open Liberty docs config examples (under REFERENCE > Features): Does the docs team need to add or update the common configuration examples to the generated feature docs?

    If so, raise an issue on the docs backlog.

    This should only be config that's commonly needed by the majority of target users (not uncommon edge cases).

And you're done.

Contacts

If you need any help:

Clone this wiki locally