User talk:Pavithraes/Sandbox/API:FAQ

Jump to navigation Jump to search

About this board

108.77.136.108 (talkcontribs)

I like that the writing here is simple and clean. I also like that the writing is friendly and informally (we and you) without being colloquial.

Most of the content is for someone with some experience with APIs already. Because of that, you may want the section on "About APIs" first, and then have the information specific to the Mediawiki API after it. This will helps folks discern whether the rest of the information is relevant to them. If they don't know what an API is, they information about specific APIs will have little meaning.

I made some corrections for grammar, but overall, there were few errors. Other editors may make changes to fix inconsistencies once you move the page into a more prominent space.

You may consider removing adjectives where you can. For instance, change "its use is strongly discouraged" to "its use is discouraged." The meaning here is the same, and we are looking to reduce and simplify where we can.

I ran the page through a tool to check the reading level: https://www.webfx.com/tools/read-able/flesch-kincaid.html It scored pretty well. This can be a good tool when working on documentation; just be aware that technical language and jargon can change the scores.

Pavithraes (talkcontribs)

Thank you for such an informative feedback! I shall keep these points in mind. :-)

Reply to "Some feedback"
Pavithraes (talkcontribs)

A skim through StackOverflow (using queries like MediaWiki API, Action API, Wikimedia API, etc.) helps us understand what an external user might look for in an FAQ.

A lot of people want guidance on how to use the API. We can point them to API:Tutorial.

Next, folks want information about performing very particular (yet basic) tasks which are mostly covered in the sidebar under 'page operations', 'search', etc. A note on navigation might be useful.


Audience for the FAQ:

- Internal and external developers who want quick answers. (or pointers on where to find the exact answers)

- Users new to MediaWiki's API looking for more information.

- Folks that are stuck somewhere who need help/need information about where to get help.

- Newcomers who lack knowledge about APIs, will need maximum support.

- (Reference: API talk:Main page#Reorganizing action API documentation)


Structure:

- The FAQ can be organized according to the types of users and the questions in the order of importance.

- The answers need to be crisp with links to additional info.

- The task description suggests splitting the FAQ into 3 sections: https://phabricator.wikimedia.org/T205167

- The 'About APIs' section is meant for beginners. It has been listed at the end to maintain MediaWiki Action API as the primary focus. This can be changed based on feedback received.

Reply to "Notes"
There are no older topics