Laura's review feedback

[lauracowen]

I've provided detailed comments as I went through but I think the guide needs revising a bit to provide more explanation and to structure the sections in more of a pyramid way (start with a summary to orientate the reader, then go into detail).

• "Learn how to use MicroProfile Config APIs to access configuration details and aggregate configuration properties into a CDI bean." - I think "into a CDI bean" isn't that helpful here. I think the abstract should focus on why accessing the details and aggregating properties is of value rather than how it's done. Why should a developer think the MP Config APIs are a good thing just from reading this sentence?
• "makes configuring your microservices a breeze" - I know we try to go a bit informal but this is maybe a bit too colloquial, esp if English is second language?
• "familiar with External configuration of microservices and" - I know that's linking to a specific doc topic but it doesn't make sense in this sentence to use a capital "E". If you're linking within a sentence like this, just write the sentence and link the relevant words to the doc topic.
  • "start with the Separating configuration from code in microservices guide" <- that's fine though because you're explicitly referring to the guide by its title.
• "because it avoids repeating the injection statement in scattered places. " <- this is the key point but it's buried way down. The why. Bring this out sooner. The how (that it's in a CDI bean) is less important at the start - no one cares how it's done until they've been convinced that they'll benefit from doing it.
• "in scattered places" - a bit awkward - get someone from ID to take a look at rephrasing.
• "Furthermore, you will also learn how to access your microservice’s configuration details." Seems odd to add this as almost an afterthought when accessing the details is mentioned first in the earlier sentences.
• I think this opening para and abstract could do with a slight re-write, maybe get @dmuelle to take a look? In general, I think it's missing some emphasis on why it matters and what the value is to a developer to use this API.

DEFINING A PROPERTY WITH EXPRESSIONS

• "A basicRegistry element is configured..." I don't understand why this is mentioned. And what it's got to do with this section.
• "Property expressions provide a way to..." This seems like it should be the start of this section. The first sentence in the section should make clear the point of the section, what to expect from the section. I don't think the section currently does that.
• "you can implement expressions with the following syntax:...." - this reads like documentation rather than a guide. The guide should be explaining; not providing reference info/docs. The guide should then link to the relevant docs/javadoc for more info. If that information isn't in the docs/javadoc, raise an issue to get that fixed.

RETRIEVING PROPERTY AS A LIST

• Again, there needs to be more explanation, and the section needs to start by succinctly introducing the section.
• Same applies to the rest of the guide.

I think maybe work with @dmuelle or other ID person (talk to David to see if he knows someone who can help) to structure the sections and provide more explanation rather than simply providing a series of steps.

[yeekangc]

Sounds like we need more of the why besides the what. =)

[dmuelle]

I reviewed this guide for ID, but I agree with Laura. It could do with more context throughout- w/in each heading it should be more clear why/when you might take that particular tac, whether by giving a concise example or clearly stating the value/benefit before getting into the actual config

[dmuelle]

please add me as a reviewer on any PR to address these comments and I can work with the writer to get it in shape