MP REST Client: ID Critique
sishida opened this issue · 4 comments
General notes:
- I'd avoid referring to "developers" or the "user" if at all possible. Refer to the developer/user as "you," or write in the imperative as a command, such as, "You can use this thing to do that task." or "Use this thing to do that task."
- If something's in a code phrase, follow it up with a word that tells what it is. These "label words" are important if we ever want to translate the guides. Some code phrases already have these words, which is great, but I also saw some without them. For example, one sentence mentions "the 'inventory' service"--that's what we want. :) That's better than just the word 'inventory' by itself. File paths, file names, URLs, etc. can all take "label words" like this.
Writing the RESTful client interface
- What makes the MicroProfile Rest Client API get added as a dependency to the pom.xml file?
--And how does this API relate to the mpRestClient-1.0 feature being enabled in the src/main/liberty/config/server.xml file? If we just want to state the fact that this feature is also enabled, maybe make the mpRestClient-1.0 feature sentence its own paragraph.
--And then the subject of the system service comes up...Maybe provide the info in these paragraphs as a list or table that states what's added, where it's added, and what it does? As it is, this section might make readers feel like they're being pulled in multiple directions in a short amount of time.
Testing the application
- I'd say "you might have introduced a bug" instead of "you must have."
Great work! You're done!
- I'd say, "They demonstrate additional technologies" and "expand on what you built in this guide."
- We try to avoid directional words because they aren't very useful to users who are visually impaired and use screen readers.
Tagging a couple comments if that's alright:
- "Rest" in "Rest Client" should be "REST". Checked and confirmed that we'd better use Rest Client
- Title: We should work on it further. I would suggest something like "Invoking RESTful microservices" or "Accessing microservices" to be consistent with the other guides. The "using" part can come in the abstract.
From Sarah:
-
The title is being discussed on Slack. From what I hear so far, my vote is for "Consuming RESTful services with template interfaces."
-
The "services" in "REST services" should be lower case.
-
I still see some code phrases that don't have description words after them, such as ResponseExceptionMappers and "The http://localhost:9080/system/properties" when it's used as part of a sentence. For example, I would say, "The http://localhost:9080/system/properties microservice..." Sometimes, all you need to do is move the description word to after the word in the code phrase. Of course, you don't need description words for standalone code blocks or when you're telling the user what to insert or type. :)
-
The word "using" can be ambiguous. Please clarify by saying, "by using" or "that uses" instead. For example, "Create graphics using Photoshop." means "Create graphics by using Photoshop." but could be construed as "Create graphics that use Photoshop." Photoshop is common enough that the meaning of this sentence is obvious, but for technical content that users might be unfamiliar with, it's better to clarify with "by using" or "that uses." The distinction might also be significant if we translate the guides into other languages.
-
Note: Some of the points under specific headings also apply to other areas of the document, not just that one section.
Try what you'll build
-
The first two paragraphs are redundant because they both mention the finish directory and trying the application. I recommend simply deleting the first paragraph/the first two sentences.
-
Use "once" when you mean "one time." For other meanings, use something like "after" or "when" instead.
Writing the RESTful client interface
-
Words like "Now" and "Then" and "Next" need to be followed by commas when they are the first word in a sentence.
-
Avoid using the pronouns "this" or "that" as standalone words. Add a noun after them, such as "This program," or replace the pronoun with a more specific noun. In some cases, you might be able to just delete the "this" or "that."
-
Also try to avoid using parenthesis. They diminish the importance of whatever's inside them. Of course, parenthesis in code are totally fine! ;)
-
Based on the points above, I'd rewrite this sentence: "That allows you to not have to worry about all of the boilerplate code (like setting up a client class, connecting to the remote server, invoking the right URI with the right parameters)." to "You don't have to worry about all of the boilerplate code, such as setting up a client class, connecting to the remote server, or invoking the right URI with the right parameters."
Handling exceptions through ResponseExceptionMappers
-
Use "might" instead of "may" to indicate possibility.
-
The word "need" can often be removed when giving straightforward instructions. Instead of, "You need to add..." you can simply tell the user, "Add..."