Reword intro to Api Overview and implicitly expand audience type #99
Conversation
Not sure if this is too dramatic. This is an attempt to address Issue thegooddocsproject#34, i.e. that "document set" was a bit unnatural. Decided to give a short sharp answer in the beginning, and tack on that initial sentence to the end of this section, which felt more natural as the preceding sentences explained the why behind it nicely.
Somewhat more concise and less vague (i.e. things and adoption). This addresses Issue thegooddocsproject#33
Until this point it was explicitly managers or engineers. Now we name these groups as examples but don't claim them to be the only group. This addresses Issue thegooddocsproject#32
Francesco-Lanciana
changed the title
|
I like your rewording to: For the following proposed change: I'm not keen on adding the final sentence: Which brings me to a final suggestion for future pull requests. I would have approved one of your changes out of three. It is always tempting to merge multiple fixes into one pull request. (I've done so myself many times - and almost always have regretted doing so because you end up in this situation where we are debating the pros and cons of multiple issues, which becomes messy, and the good issues don't get approved. |
Having "Always" immediately after the heading meant that it was connected to the heading which breaks the style guide. Also in line with Camerons suggestions I have opted to move the final sentence to the beginning so it adds new imformation rather than simply reinforce what we had said previously
|
You make a good point, I'll make a point of keeping each change in a seperate PR to avoid this situation in the future :) I've made changes to rectify those two things you bought up. Let me know what you think. |
api-overview/about-overview.md
Outdated
| @@ -2,43 +2,43 @@ | |||
|
|
|||
| ### When Do I Need an Overview? | |||
|
|
|||
| Every document set should include an overview. This document tells potential users or buyers of the product the things they might want to know before adoption. | |||
| Your API documentation should always include an overview document. This document tells potential users or buyers what they might want to know before deciding to use your API. | |||
There was a problem hiding this comment.
-
There is a subtle generalisation introduced here which could be interpreted to be technically incorrect. "Every document set" refers to a set of documentation, and hence justifies an overview. "Your API documentation" might be a single API, and hence need not include an overview.
-
I prefer "should" over "should always". "should always" mixes the meaning of "most times" and "always". If you mean "always" then words like "must" and "shall" are usually better. Also best to be concise and use only 1 word instead of 2. It makes the doc easier to understand. However, there are almost always edge cases in documentation. Adding "always" breaks this guidance. From memory, the Google style guide reference to guidance over rules for the same reason.
-
I prefer "before adoption" to "before deciding to use your API". Reason: Less words means more concise. Also "adoption" covers more use cases than "deciding to USE your API". It also doesn't lock you to the API use case.
There was a problem hiding this comment.
I like you suggested change:
-
From: buyers of the product the things
-
To: buyers what they
There was a problem hiding this comment.
I've implemented the second two changes, however with regards to "Every document set" I would assume that the people coming to this for guidance wouldn't be those with a single API. Also just to clarify do you mean a single API endpoint? I thought even that should have a quickstart if it isn't a simple public endpoint which most aren't, and since it would have some kind of a reference manual than that would also be a set. So then wouldn't someone having a single API with the need to only have one document be a very edge case we shouldn't focus on?
|
|
||
| Many users install or plug into your service immediately because they are already familiar with it or someone else has decided that the team will use this solution. All of those people will go to your Quickstart, or will just get to work. | ||
|
|
||
| There are other groups, however, who need to assess your product in order to decide whether they want to use it. They are either the managers responsible for a business decision, or they are engineers who don't know enough about your product to decide whether it can accomplish what they want it to do. People who fall in either of these groups might decide not adopt your product unless you provide an overview that answers their questions. | ||
| There are other groups, however, who need to assess your product in order to decide whether they want to use it. For example, managers responsible for a business decision or engineers responsible for a technical assessment of your product. People in these groups might decide to not adopt your product unless you provide an overview that answers their questions. | ||
|
|
There was a problem hiding this comment.
Recommendations in this section looks good.
api-overview/about-overview.md
Outdated
| * Is it intended for a particular industry. | ||
| - Are you writing only for developers? For managers? | ||
| - Are you writing only for people who have a certain problem to solve? | ||
| - Is it intended for a particular industry. |
There was a problem hiding this comment.
I don't see the point in switching from bullet point formats. Unless we have set a convention across all docs, (which I don't think we have done), I suggest keeping the same as before, so you don't introduce extra review time for people.
Ditto for other lists in this file.
There was a problem hiding this comment.
This was my mistake, my formatter automatically converted it and I didn't notice, I'll convert it back. I think we should add some kind of formatter config so that keeping it consistent over many contributions becomes easy
Should always infers a rule rather than guidance, this is not in keeping with our or googles guidelines so I have reverted it. Also "deciding to use your API" is much longer than "adoption" and doesn't communicate anything more therefore this has been reverted as well.
|
Sorry for the delay in getting these changes through (have been waaayyyy to busy recently). @camerons now just waiting on guidance for "Every document set" vs "Your API documentation" 👍 |
|
Thanks for these updates @Francesco-Lanciana. I'll merge the pull request. |
Hopefully resolves #32 , resolves #33 and resolves #34
Decided to give a short sharp answer in the beginning (not sure if this is too dramatic), and tack on that initial sentence to the end of this section, which felt more natural as the preceding sentences explained the why behind it nicely.