Skip to content

Documenting Open Liberty

Jump to bottom
Laura Cowen edited this page Nov 26, 2020 · 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 project on the Open Liberty website:

How do I decide where my runtime change should 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.

Check each of the following types of content to see whether you need to provide new or updated information for the target user to be able to use your runtime changes:

  1. Does an existing guide need updating?

    To request changes to published guides, raise an issue on the guides backlog.

  2. Do we need to develop a new guide?

    If you propose a new guide, and your proposal is accepted, it will be prioritised for development and discussed further with you.

    To propose a new guide, raise an issue on the guides backlog.

  3. Do the existing Open Liberty doc topics about this area of the Open Liberty runtime need updating?

    To request updates to existing doc topics, raise an issue on the docs backlog:

    • What do 80% of target users need to know to be most easily productive using your runtime update?
    • Indicate which release the runtime updates will target. The Open Liberty docs team will aim to get the docs updates published as soon as possible.

  4. Do we need to write new topics in the Open Liberty docs?

    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.

    To request that new information is added to the Open Liberty docs, raise an issue on the docs backlog:

    • You do not need to define or write the individual topics as the docs team will work that out. They might ask for more information to help with this.
    • Provide the information that a user would need to use the runtime feature and why they would need it (give some example scenarios).
    • 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.
    • Indicate which release the runtime updates will target.

    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.

  5. Do we need to add or update the common configuration examples to the generated feature docs (under REFERENCE > Features)? This should only be config that's commonly needed by the target users (not uncommon edge cases).

    To propose a new config example or suggest changes to an existing one, raise an issue on the docs backlog.

  6. What does the target user need to know about your runtime update when it's announced in the release blog posts? Provide an entry for the release blog posts about your runtime update. This can be used in both the beta release blog post and GA release blog post.

    To provide information for the beta release blog post, raise an issue on the open-liberty backlog.

    To provide information for the GA release blog post, raise an issue on the open-liberty backlog.

  7. Optionally, write a standalone blog post about your new runtime update. This must not be a comprehensive set of documentation; 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.

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

Contacts

If you need any help:

Clone this wiki locally