Web APIs hub/Contributing

From MediaWiki.org
Jump to navigation Jump to search

Proposing articles[edit]

You can propose an article for the Web APIs hub in Phabricator.

  • The link above creates a task in the #web-apis-hub and #documentation projects; add the primary technical project to which it's related
  • Title the task "showcase/inspire: what it does", unless the task is for underlying documentation such as "Improve OAuth documentation" or "Develop Wikidata API sandbox"
  • If it depends on some infrastructure development, make it blocked by that phabricator task
  • Link to any existing documentation, wikitech-l threads, phabricator discussions, etc. (There is always existing documentation!)

Sharing your pain points[edit]

Just knowing where developers have problems is very valuable. File a bug in #Web-APIs-hub and #MediaWiki-API referencing your API talk:action API topic or your wikitech-l mailing list post; if you already have a bug in Phabricator add the tags #Web-APIs-hub and #documentation to it. Or, as of August 2015, e-mail SPage (WMF) (talk)

Writing articles[edit]

Take an article from "Article candidates" on the #web-apis-hub workboard, assign it to yourself and start writing! Use the API: namespace on mediawiki.org for now. API:Page info in search results is a good starting point for a showcase/inspire article.

The intent of a showcase/inspire article is to

  • showcase (with a screenshot) some cool use of Wikimedia data or API
  • explain how it works, wherever possible using interactive examples that let the reader try the API calls
  • encourage the reader to go further with a concrete next step

Opening wikitext[edit]

{{TNT|Draft|early article for [[Web APIs hub]]}}
{{Dev-Article}}
{{TNT|Dev-Call to action|invite=What you want developers to do.}}

Article structure[edit]

  • brief Introduction
  • Set out the problem area
    • Underlying MediaWiki technology
    • How it works on Wikimedia wikis
  • Additional areas
    • Performance concerns
  • Next steps
  • See also

When you save your draft, mention the Phabricator TNNNN task in the edit summary. Add a comment to the phabricator task linking to the draft.

Screenshots[edit]

Find good screenshots on commons or upload your own. Never full-screen, find the key point. XXX licensing

Use templates[edit]

This is evolving, the location of articles will change. So don't repeat yourself. Templates: {{git file}}, {{ApiEx}}, {{Api help}}}, etc. Reference Phabricator heavily with [[phab:TNNNN]]. The pages are internationalized for easy localization, so you prefix most template invocations with {{TNT}} to ease localization, as shown in #Opening wikitext.

Style[edit]

Conversational, non-officious. "Do this", "try that", "You can"; "We see..." when walking through steps.

Explain what's going on, but don't get lost in detail; instead link to underlying API documentation or even source code.

More at Documentation/Style guide and User:SPage (WMF)/On tech writing

Updating the landing page[edit]

When you think your article is good enough to feature on the landing page, assign its Phabricator task to SPage and say so in a comment. If agreed SPage will excerpt the article and its lead image.

We could fill this section with process and review, but just do the right thing. The landing page should be coherent, whatever it links to should be professional.

Eventually we'll have more than three articles and areas to explore. We'll either rotate them, have an in-page gallery to show more, link to category of additional articles, etc.

Fixing generated documentation[edit]

The Data & Developer Hub relies heavily on generated documentation from api.php, ApiSandbox, phpdoc, etc. If you can see improvements in the comments, API help, parameter doc, etc., either

  • fix it yourself: create a Gerrit patch that makes the change, make sure to put "comment only" or "doc only" in the commit title and summary.
  • file a phabricator task against the relevant project, add project #dev.wikimedia.org, and tag #Easy, and suggest the exact change. Again, put "comment only" or "doc only" in the title so people know you're not changing internals.

Updating doc.wikimedia.org[edit]

See Continuous integration/Documentation generation