1874278 - [Docs] Reduce duplication between experimenter.info and firefox-source-docs

Status: NEW

(Firefox :: Messaging System, task, P3)

Description

[Shane Hughes [:aminomancer]]

The desktop messaging surfaces page has some redundancy with the UI templates section of our firefox-source-docs page. But it also has some benefits that aren't present there, like having screenshots of multiple surfaces in one place. It also has more modern language.

Since experimenter.info is about experimentation, I think it shouldn't have a desktop messaging surfaces page at all. The messaging experimentation guide should just link to the surfaces on firefox-source-docs. But we can also make some improvements to firefox-source-docs by copying over from or imitating the experimenter.info page. So just try to transfer the desktop messaging surfaces page from experimenter.info to firefox-source-docs. That way we won't need to update 2 documentation sites (or fall behind on one of them), we can just link to/from each of them when appropriate.

Comment 1

[Punam Dahiya [:pdahiya]]

We should provide better cross link between these two documentation surfaces each serving a unique need ( source doc - more technical documentation for Engineering audience and github messaging surafces - simplified language for messaging system customers ).

Examples in Source doc text on page https://experimenter.info/messaging/desktop-messaging-journey should be linked to UI templates https://firefox-source-docs.mozilla.org/browser/components/newtab/content-src/asrouter/docs/index.html#ui-templates

and vice versa by adding link to desktop messaging surfaces from UI templates

Comment 2

[Shane Hughes [:aminomancer]]

Here's my rationale for wanting to consolidate the screenshots - the distinction in my mind is less between technical docs and simple docs, and more between experimenter docs and firefox docs. Our documentation on firefox-source-docs is about the surfaces, triggers, targeting, etc., while the documentation on experimenter.info currently feels all over the place, but I think it should be about experimenter-specific features, like messaging feature IDs, measuring reach, experimental message l10n, multi-message feature configs, etc. (After all, it's experimenter.info, not fxms.info)

For example, does this page need a section on local message providers? It seems unrelated to experimenter. And yet, firefox-source-docs doesn't have any info about local message providers, IIRC. I'm not sure experimenter.info should even have a page about the messaging journey/system, but FxSD definitely should The rationale for FxSD is to keep the docs and the code it documents together, in one place, since that reminds us to keep it updated.

It's easier to maintain the docs if they're on FxSD, as everyone uses phabricator and has this repo open constantly. The reason experimenter docs don't get updated as often is because we aren't really responsible for that repo, so nobody bothers to clone it and use it often. So it just gets left behind. And firefox source docs are updated daily, so it doesn't need to ride the trains.

Anyway, this feels like a central "messaging system" landing page (it's a bit unfortunate that it's in the newtab directory though), while the messaging section on experimenter.info feels like an obscure section of the docs for an entirely different product.

It would be more discoverable if it was linked from the central messaging system page on FxSD, though. I think it could have a bullet point in the table of contents labeled "Messaging Experiments" or something. We reference "experiments" on that page, but we don't have any docs about how to do an experiment. So it seems appropriate that we'd send users to experimenter.info for instructions on how to run a messaging experiment. But I don't think we need to host screenshots of messaging surfaces on experimenter.info, as the surfaces are part of Firefox proper.