Page MenuHomePhabricator

Clean up grammar in API autodocs
Closed, ResolvedPublic

Description

I'm not sure where the "Documentation" section of ApiSandbox comes from, but it currently has inconsistent (and, in some cases, wrong) grammar.

Examples:

list=exturlusage --> euquery --> "Protocol of the url. If empty and euquery set, the protocol is http.
Leave both this and euquery empty to list all external links"

"URL" should be capitalized.

action=clicktracking --> "Track user clicks on JavaScript items."

Ends in a period?

action=coderevisionupdate --> "Submit comments, new status and tags to a revision"

No final period?

action=wikiloveimagelog --> "This API is for logging each time a user attempts to use a custom image via WikiLove."

"This API"? This isn't consistent language with the documentation for the rest of the parameters. And it ends in a period.

These are just a few examples. Consistent style should be applied throughout. If the text is going to end in periods, it should end in periods every time. If "URL" is going to be capitalized (when used in documentation text), it should be consistently capitalized. Etc.


Version: 1.20.x
Severity: trivial

Details

Reference
bz34965

Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 12:11 AM
bzimport set Reference to bz34965.
bzimport added a subscriber: Unknown Object (MLST).

action=emailuser --> "Email a user."

MediaWiki fairly consistently uses "e-mail" and there's a trailing period here. Just another example.

I fixed the extraneous period in Gerrit change #34965.

IMHO, this should be closed and individual tickets opened for each offender. Thoughts?

(To be more specific: the extraneous period in the ClickTracking extension.)

I guess we want to fully review our API documentation and fix all/most of the grammar issue.

(In reply to comment #4)

IMHO, this should be closed and individual tickets opened for each offender.
Thoughts?

Individual Bugzilla tickets for each typo? That's a bit insane.

(In reply to comment #6)

I guess we want to fully review our API documentation and fix all/most of the
grammar issue.

Yes. :-)

Related URL: https://gerrit.wikimedia.org/r/69953 (Gerrit Change Ia1df9748b5de33f6ef5088103ccc6b886f9a17d5)

(In reply to comment #0)

list=exturlusage --> euquery --> "Protocol of the url. If empty and euquery
set, the protocol is http.
Leave both this and euquery empty to list all external links"

"URL" should be capitalized.

see gerrit 69953

(In reply to comment #1)

action=emailuser --> "Email a user."

MediaWiki fairly consistently uses "e-mail" and there's a trailing period
here.
Just another example.

See bug 45633

(In reply to MZMcBride from comment #0)

list=exturlusage --> euquery --> "Protocol of the url. If empty
and euquery set, the protocol is http.
Leave both this and euquery empty to list all external links"

"URL" should be capitalized.

Was changed by gerrit 69953

action=clicktracking
--> "Track user clicks on JavaScript items."

Ends in a period?

Extension is no longer active.

action=coderevisionupdate --> "Submit comments, new status and tags to a
revision"

No final period?

Changed with gerrit 117925

action=wikiloveimagelog --> "This API is for
logging each time a user attempts to use a custom image via WikiLove."
"This API"? This isn't consistent language with the documentation for the
rest of the parameters. And it ends in a period.

Changed with gerrit 117914

(In reply to MZMcBride from comment #1)

action=emailuser --> "Email a user."

Was changed with gerrit 51846

You should add seperate bugs for the typos, maybe grouped by extension, to allow the extension authors to track this individual.
Or create a (user) wiki page to track the necessary changes.