This Hypothesis is part of key result DE2.2 of the Wikimedia Foundation's annual plan: "Pilot Wikipedia Integration: Demonstrate the first integration of an Abstract Wikipedia article into Wikipedias":

If we simplify the process of creating a new language-specific Function, then it will be easier for the community, and specifically pilot communities, to create language-specific Functions.

Reasoning

Creating a language-specific Function today is a complex process. It requires a substantial understanding of Wikifunctions and of the relationship between NLG Functions, configurations and language-specific Functions. We have started to work with pilot communities, and will ask them specifically to create language-specific Functions for existing NLG Functions. A simpler process should make it easier for these communities to create the Functions they need.

Success metric

Reduce the number of steps needed to create a language-specific Function.

We measure this on-wiki:

1. (Primary) The pages and manual steps needed to add a language to "defining role sentence". Baseline is the count recorded from Milestone 0; target is for it to be a one page action, with no ZIDs and no argument types, counts or order typed by hand.
2. The share of new language-specific Functions that reach each stage: implemented, connected, and registered. This shows where users stop. Measurable from Milestone 1, when the link to the dispatching Function exists.
3. Coverage of the focus languages (Igbo, Malayalam, Dagbani, and English): the share of NLG Functions used by pilot articles that have a registered language-specific Function for each of these languages. Baseline: the configurations at the start of Milestone 0.
4. Context only, not a target: the number of new language-specific Functions registered each month. Baseline: the configuration histories.

Readiness criteria

• From the page of a dispatching NLG Function, a user can start to create a language-specific Function for their language. The new Function already has the inputs and output of the dispatching Function, and the user does not type any ZIDs by hand.
• In the same flow, without a change of page, the user can write the first implementation and the first tests for the new Function. These are connected through the normal Wikifunctions approval process.
• The page of a dispatching NLG Function lists its language-specific Functions and their languages, including Functions that are not yet registered. Each entry links to the place to add tests, so a user who cannot write an implementation can still contribute.
• A user with the right permission can register a language-specific Function for a language. If that language is already registered, they see a warning before they save.
• Straight after registration, an abstract article on Abstract Wikipedia that uses the NLG Function renders in that language with the new Function.
• For the reference example (add a language to "defining role sentence"), the number of pages and manual steps falls from the Milestone 0 baseline to the target.

Milestones

Each milestone has its own sub-task, with the detailed work, acceptance criteria, and what is not in scope. Milestones 1 and 2 are provisional until the decision in Milestone 0, and we will rewrite them to match it.

• Milestone 0: Map the current process, record the baseline, and decide the approach. We find out how hard it is today to add a language to an NLG Function, measure the current costs, and decide how we will store the link between NLG Functions and their language-specific Functions.
• Milestone 1: Create a pre-filled language-specific Function from its dispatching NLG Function, and keep the link between them. A user starts from an NLG Function and creates a language-specific Function for their language on one page, with its first implementation and tests.
• Milestone 2: Register a language-specific Function in its configuration. A user with the right permission puts the new Function into use with one action, and sees the result in an abstract article straight away. This is blocked on separate work on the permissions for configurations.
• Milestone 3: Validate with pilot communities against the baseline. We measure the new process on-wiki for two weeks after Milestone 2 is deployed, and state whether the hypothesis was supported.
• Milestone 4 (stretch): Show which languages are missing, and invite users to improve the output for their language.

Terminology

• NLG Function: a Function that takes language-independent inputs and a language, and returns text in that language. It does not contain any language's grammar itself. There are two kinds:
  • HTML NLG Function (e.g. Z37011, "defining role sentence (HTML)"): returns HTML. Abstract articles call these for fragments. This is the form that we want all NLG Functions to have in the future.
  • Monolingual NLG Function (e.g. Z28016, "defining role sentence (monolingual)"): returns monolingual text. This is the older form. HTML NLG Functions slowly replace these; many HTML NLG Functions currently wrap one.
• Dispatching NLG Function (proposed term): the NLG Function whose implementation looks up the right language-specific Function in a configuration. Today this is usually a monolingual NLG Function; in the future it will be an HTML NLG Function.
• Language-specific Function (e.g. Z28026 for English, Z32166 for French): a Function with the same inputs and output as its dispatching NLG Function, which writes the text for one language or a group of languages.
• Unregistered language-specific Function: a language-specific Function that is linked to its dispatching NLG Function but not yet in the configuration, for example because it has no connected implementation yet. It is not used at run time, but users can find it and add tests.
• Configuration (e.g. Z28020, an instance of Z14294): a list of options. Each option pairs a language-specific Function with one or more languages. The configuration also names a default Function.
• Default Function (e.g. Z28019): the Function used when no option matches the requested language.
• Register (proposed term): add an option for a language-specific Function to a configuration. We use "register" so that this is not confused with the existing Wikifunctions term "connect", which is the approval of an implementation or test for a Function.
• Live (proposed term): a registered language-specific Function that the selector uses at run time. Depending on the decision in Milestone 0, registration and going live may be one step or two; for example, a registered Function with tests but no working implementation yet would not be live.
• ZID: the identifier of an object on Wikifunctions, such as Z28016.
• Orchestrator: the Wikifunctions service that runs Function calls.
• function-schemata: the shared definition of the built-in types on Wikifunctions, such as the Function type (Z8).

Current process

This is our reading of the process today, for the example of adding Welsh to "defining role sentence". Milestone 0 confirms it and counts it.

1. Find the monolingual NLG Function behind the article fragment: open Z37011, then its implementation Z37044, and find Z28016 inside it.
2. Find the configuration: open Z28016, then its implementation Z36298, and find Z28020 inside the composition.
3. Create the language-specific Function, and copy the signature by hand (three Wikidata item references and a language, returning monolingual text).
4. Create at least one test, and get it connected.
5. Create at least one implementation, and get it connected.
6. Edit Z28020 to add an option with the new Function and the language.

Known problems with this process:

• Nothing on an NLG Function's page links to its configuration. Users find it only by reading inside an implementation.
• Users copy the signature by hand. A mismatch is not detected when they save.
• Nothing warns a user that their language is already registered. When the same language is in two options, the first match is used, but this is a side effect of the implementation, not a rule.
• Nothing invites users to add their language when it is missing, or to add tests or fix the implementation when they think that the output for their language is wrong.

Prior art

• The community-built configuration pattern: the types Z14294 (configuration) and Z14293 (Function option), and the selector Function Z14310.
• The apply mapper Z34039, which calls the selected language-specific Function with the dispatching Function's arguments.
• The existing Wikifunctions flows to create a Function, and to connect implementations and tests to it.
• David S.'s tool abstract-data, which shows some of the same information that Milestone 4 adds to Wikifunctions.

Non-goals

• Change who can edit configurations. Separate work changes these permissions. Milestone 2 waits for that work, and uses the permissions that it defines.
• Migrate monolingual NLG Functions to HTML NLG Functions. That work continues on its own schedule. What we build must work for dispatching NLG Functions of both kinds.
• Write implementations or tests for users, or judge the quality of language output. We give users one flow to write them in; the content stays the community's work.
• Create new NLG Functions or new configurations. This hypothesis is about adding languages to NLG Functions that already exist.
• Change the rule that selects a language-specific Function at run time. We warn about duplicate registrations, but we do not define a new precedence rule.
• Change how users unregister a language. Removal stays a normal edit to the configuration, and is part of the separate permissions work.

Open questions

Milestone 0 answers these.

• Do we build a new content system for the relationship between NLG Functions, configurations and language-specific Functions, or take small iterative steps on the current on-wiki conventions?
• Where do we store the link between a dispatching NLG Function and its language-specific Functions? It must exist before registration, so the configuration cannot be the only record of it.
• Do we make dispatching NLG Functions a new top-level type, which in general returns monolingual HTML (Z91)? Such a type could hold its configuration and its language-specific Functions directly, which would also answer the question above.