Talk:Documentation/API documentation/Overview
Add topicLatest comment: 2 months ago by TBurmeister (WMF) in topic Reflections upon first real usage
Reflections upon first real usage
[edit]As I attempted to apply this doc structure to the Mediawiki REST API docs (phab:T405972) I encountered the following potential pitfalls and revision ideas:
- Location of section content: The docs I tested this with didn't need a separate overview page, so all the content is on the landing page. This feels correct, and it made me realize I wouldn't want the usage policies to be buried on an Overview subpage; I think those policy sections should move to the landing page. BUT that depends on some of the complexity below: if they're just links, it's fine to put them on the landing page, but if they're long paragraphs, that is problematic.
- Sample call and URL structure feel most useful within the context of an action-oriented quick start or getting started tutorial (example), rather than overview. I'm leaning towards making the link to the quick start very prominent and trusting that (based on what devs have told us and we've observed), people gravitate to these pages first, so they will quickly find the info. I think the intent of including it on the Overview page was that we want to communicate quickly and early how simple/complex the API's call structure is, and the data formats it supports. But then that same information must be included in the quick start. I'm leaning towards it being better there instead of in the overview.
- Usage and access requirements: many API doc collections have their own versions or subsets of these types of guidelines, but WMF has official versions: User-Agent policy, API Usage guidelines, and Robot policy. Everything that I found in the current MediaWiki REST API docs that related to rate limits and client identification (user-agent headers) was already covered in more authoritative detail in the "official" policy docs. This presents a quandary, however, because those docs are overwhelming and long. If we extract subsets of the info we are creating problematic duplication, but users need to know and use that key info within those very large docs. Maybe there's a need to improve the policy docs' structure? Not sure that would help with this.
- I also struggled with the nuance between overview "info you should know" in this domain, vs. how-to "info you must use when doing a real thing". For example:
- It's a policy to say you must have a user-agent header; it's a how-to instruction to tell you how to do that and how to get around Javascript-related nuances you may encounter.
- It's a policy to say "don't abuse the service or overload it with requests"; it's a how-to instruction to tell people how to use conditional requests or other strategies to limit their requests and engage in responsible resource usage. In the draft for the MediaWiki API docs, I navigated this by including links to the policies in Overview, and a "before you start" section that refers back to that in the quick start. It's still a problem that the quick start doesn't have any content about using a user-agent header; the user must click the links to read and follow the policies and instructions that are on a separate wiki. I don't like this, it doesn't feel friendly nor sustainable. And it's a recurring issue that will continue to come up as a challenge for all doc collections.
- I also struggled with the nuance between overview "info you should know" in this domain, vs. how-to "info you must use when doing a real thing". For example:
- Content attribution guidelines (larger scope than this doc work, but the work is consistently impacted by this larger issue): similar issue as outlined above for policy docs. There are too many of them and they are very long, but I'm not sure there's any way to avoid that since we mustn't create content that diverges from the "official" policy -- though it could be much clearer what that is. I think for API users it's supposed to be Developer App Guidelines but what if I'm not building an app as an API user? This also doesn't address how an API user should understand the content reuse guidelines they'll find across the specific projects and language editions from which they maybe using the API to get content: