search

OpenLiberty / guides-common

Common Guide files
Other
9 stars 6 forks source link

Improve MicroProfile Config guides #158

Open cajaygle opened 6 years ago

cajaygle commented 6 years ago

Static MicroProfile config guide: “Configuring microservices — Learn how to provide external configuration to microservices using MicroProfile Config"

Interactive MicroProfile config guide: “Separating configuration from code in microservices - Learn how to perform static configuration injection using MicroProfile Config.”

If I'm a developer it's not clear to me how these two guides are the same and how they are different. We should clarify this -- for example, by aligning and differentiating the titles and descriptions.

JunyiSun commented 6 years ago

Hi @cajaygle , The static guides covers the following topics: static injection, dynamic injection, custom config sources, and custom config converters.

As far as I remember, the interactive guides mostly covers static injection, not much about other topics.

Thank you.

mbroz2 commented 6 years ago

in short, the interactive guide is an 'intro' whereas the static guide is more of a 'deep-dive' or 'advanced' guide. I agree with @cajaygle that we don't do a good job explaining that to the user via title/description. However, I wonder if the solution should be specific to just these 2 guides, or more universal to our guides (aka, should we consider 'marking' some guides as 'beginner', 'intermediate', and 'advanced' (and I don't mean those terms specifically, just the concept behind them).

cajaygle commented 6 years ago

In this case what might make sense is to label the interactive guide as an "Introduction to MicroProfile config" and label the static guide as a deeper dive. Word the titles and descriptions similarly so that the relationship is clear. And perhaps at the start of the static guide we mention the interactive guide as a starting point.

cajaygle commented 6 years ago

And, agree, that we could look at this for all the guides. how to label intro, beginner, deep dive guides

yeekangc commented 6 years ago

Besides the issue(s) raised above, we have improvements in/for MP Config 1.3 that changed the picture on what we should covered. We should take another look at our MP Config guides, work out what needs to be done, how we should organized them and do them.

What we should consider for MP Config 1.3 includes mapping config properties to environment variables and server.xml as dynamic configuration source.

Repurposing or expanding this issue to cover all the above.

yeekangc commented 6 years ago

I can see that we have 1 intro MP Config guide that aligns with the Interactive guide and then a more advanced MP Config guide that is static alone. And, they would cover MP Config 1.3 or above.