added documentation for real life usage and profile history #165
Conversation
|
Some typos: https://travis-ci.org/mozilla/firefox-data-docs/builds/411230832#L666-L689 "stubinstaller" should probably be "stub installer". "client_id" should be "client ID" in a sentence (unless referring to the dataset field). The others are actualy typos. |
|
@badboy , good catch! Fixed the typos.
|
| @@ -0,0 +1,135 @@ | |||
| # Real World Usage | |||
|
|
|||
| This page backs away from our profile-focused data view and examines what Firefox usage looks like in the real world. There are many components and layers that exist between a user acquiring and running Firefox, and this documentation will illuminate what those are, and how they can affect the meaning of a profile. | |||
There was a problem hiding this comment.
We should make it clear that this only focuses on Firefox Desktop
| * 4: OS user profile | ||
| - Most operating systems allow users to log into different user profiles with seperate user directories (such as a "Guest" accounts). | ||
| - Usually, Firefox is installed into a system directory that all users profiles will share, but Firefox profiles are saved within the user directories, effectively segregating them. | ||
| * 5: FF binary / installer |
There was a problem hiding this comment.
I think we should expand this abbreviations here. FF => Firefox
| - Usually, Firefox is installed into a system directory that all users profiles will share, but Firefox profiles are saved within the user directories, effectively segregating them. | ||
| * 5: FF binary / installer | ||
| - The downloaded binary package or stubinstaller which installs Firefox into the hard drive. Users can get these from our website or one of our managed properties, but they can also acquire these from 3rd party sources as well. | ||
| - Our website is instrumented with GA to track download numbers, but other properties (FTP) and 3rd party sources are not. GA data is not directly connected to Telemetry data. |
| * 5: FF binary / installer | ||
| - The downloaded binary package or stubinstaller which installs Firefox into the hard drive. Users can get these from our website or one of our managed properties, but they can also acquire these from 3rd party sources as well. | ||
| - Our website is instrumented with GA to track download numbers, but other properties (FTP) and 3rd party sources are not. GA data is not directly connected to Telemetry data. | ||
| - A user can produce multiple installations from a single FF binary / installer. For example, if a user copies it to a USB stick or keeps it in cloud storage, they could install Firefox on multiple machines from a single install. |
There was a problem hiding this comment.
- from a single install
+ from a single binary / installer| * 7: FF profile | ||
| - The profile Firefox uses during a user's session. | ||
| - A user can create multiple Firefox profiles using the Firefox Profile Manager, or by specifying a custom directory to use at startup. More details [here](link to Jan Erik's documentation). | ||
| - This is the entity that we see in telemetry. A client_id corresponds to a specific profile (however, a client_id does not always correspond to a single profile sitting inside a single computer). |
There was a problem hiding this comment.
We should treat "Telemetry" as a name and title-case it (telemetry -> Telemetry)
There was a problem hiding this comment.
We should make it more clear that Telemetry identifies a profile by a client id.
Something along those lines:
"A profile is identified by a client ID, which is used by Telemetry as the identifier and contained in pings."
(Feel free to change the wording)
|
|
||
| In telemetry, this user would just show up as a single `client_id`. | ||
|
|
||
| Assuming they went through our normal funnel, they should show up once in GA as a download and once in stubinstaller pings as a new installation (if they used a stubinstaller). |
There was a problem hiding this comment.
If we expanded GA once before we could continue to use the abbreviation here.
|
|
||
|  | ||
|
|
||
| In telemetry, this user would just show up as a single `client_id`. |
|
|
||
| Think of the situation where the IT staff sets up the computer for a new hire at a company. Instead of going through to trouble of installing all the required programs and setting them up correctly for each computer, they'll do it once on one computer, save the disk image, and simply copy it over each time they need to issue a new machine. | ||
|
|
||
| Or think of the case where the IT staff of a library or PC Bang needs to set up 2 dozen machines at once. |
There was a problem hiding this comment.
I had to look up "PC Bang" because I was not familiar with the term. Maybe we can leave it out?
|
|
||
|  | ||
|
|
||
| In this case, there will not a second download event, but there will be an install event and the new and old machines will have seperate `client_id`s. |
There was a problem hiding this comment.
- will not a second download event
+ will not be a second download event| * 1: The user | ||
| - A human being presumably. | ||
| * 2: The machine | ||
| - They physical hardware running Firefox. |
|
good points! made requested changes |
|
Rendered (also includes my draft coming in another PR) |
|
One thing I forgot to note: I haven't reviewed the "Profile History" chapter yet. |
|
noted! |
high_level/profile/realworldusage.md
Outdated
|
|
||
| #### Migrations | ||
|
|
||
| * Type 1: Migrate Disk Image |
There was a problem hiding this comment.
Can you make these sub headings?
high_level/profile/profilehistory.md
Outdated
| Diagram: | ||
|  | ||
|
|
||
| It's possible this behavior is due to dropped pings or pings that never reached us due ping sending logic. |
SUMMARY.md
Outdated
| * High-level Behavior | ||
| * Profile Behavior | ||
| * [Real World Usage](high_level/profile/realworldusage.md) | ||
| * [Profile History](high_level/profile/profilehistory.md) |
There was a problem hiding this comment.
For order, should we have the profile details (history, creation) first? Or the real-world usage?
Either way could make sense i guess.
There was a problem hiding this comment.
I think Real World Usage should come first, or be a level above the profile details. But I'm open to ideas!
|
@mreid-moz @harterrt This is a starting point on documenting profile behavior as it relates to data & Telemetry. |
|
@georgf , changed the bullets to headings and fixed the typo. Also, I slightly changed the diagram organization |
|
Thanks, All! I'd title this section "Telemetry Behavior Reference", but the placement in SUMMARY.md makes sense to me. Can you list some example "Coming soon" articles? That may help characterize the section. Can we keep the source documentation in the |
|
So far we will also have some technical docs how firefox uses profiles (#166). (Taking over from Su, doing the re-organization) |
No change in content (except section title)
badboy
dismissed
their stale review
Taking over, review from someone else needed
|
@harterrt Are you ok with the structure inside data docs now? |
|
@chutten Can you take a final content review pass over it? |
There was a problem hiding this comment.
The structure and content appear correct to me. I have some grammatical suggestions that can be taken to follow-ups after this is merged.
The only thing that prevents landing is supplying the "link to janerik's documentation" in Real World Usage. Everything else could be handled in future iterations.
concepts/profile/realworldusage.md
Outdated
| - Usually, Firefox is installed into a system directory that all users profiles will share, but Firefox profiles are saved within the user directories, effectively segregating them. | ||
| * 5: Firefox binary / installer | ||
| - The downloaded binary package or stub installer which installs Firefox into the hard drive. Users can get these from our website or one of our managed properties, but they can also acquire these from 3rd party sources as well. | ||
| - Our website is instrumented with Google Analytics to track download numbers, but other properties (FTP) and 3rd party sources are not. Google Analytics data is not directly connected to Telemetry data. |
There was a problem hiding this comment.
At this point it might be relevant to mention attribution's role in identifying the source of the installed firefox.
There was a problem hiding this comment.
good point. i'm also working on separate documentation explaining the attribution process, will link it to this doc in the future.
concepts/profile/realworldusage.md
Outdated
|
|
||
| In this case, the old machine and the new machine will just share the same client ID (assuming that the disk was copied after a Firefox profile was created). In fact, it will look exactly like the Cloned Machines case, except that instead of sending pings concurrently, they'll be sending us pings first from the old machine and then from the new machine. | ||
|
|
||
| Also, it should be noted that their Firefox profile will 'revert' back to the state that it was in when the disk image was copied, essentially starting over from the past. |
There was a problem hiding this comment.
(and any unsent pings in the image will be resent)
There was a problem hiding this comment.
good point, will add
|
@chutten , thanks for the notes. will update with new commit |
concepts/profile/profilehistory.md
Outdated
| * `profile_subsession_counter` | ||
| - A counter which starts at 1 on the very first run and increments for each subsession. This counter will be reset to 1 if a user resets / refreshes their profile. | ||
| * `subsession_start_date` | ||
| - The date the subsession occurs in. This field is not always reliable, either due to local clock skew or other less understood reasons. |
There was a problem hiding this comment.
What are these less understood reasons? Or do we not know why the field is unreliable?
concepts/profile/profilehistory.md
Outdated
|
|
||
|  | ||
|
|
||
| This is a nice clean example of profile history. It has a clear **starting ping** and it progresses linearly, with each subsession connecting to the next via `subsession_id`. However, due to the fact that profiles can be shared across machines, and restored manually, etc. ([see here](section1-realworldusage.md)) strange behaviors can arise. |
There was a problem hiding this comment.
"see here" is a dead link
concepts/profile/profilehistory.md
Outdated
|
|
||
| There is a gap in the profile history. | ||
|
|
||
| It's possible this behavior is due to dropped pings or pings that never reached us due to ping sending logic. |
There was a problem hiding this comment.
Is the ping sending logic a known issue?
There was a problem hiding this comment.
The logic itself shouldn't be the problem. To my knowledge we don't know about any actual issue here.
concepts/profile/profilehistory.md
Outdated
|
|
||
| ## How to Order History | ||
|
|
||
| (Work in Progress) |
There was a problem hiding this comment.
Please reference a tracking bug so the reader can ask questions
concepts/profile/profilehistory.md
Outdated
|
|
||
| #### History Reruns | ||
|
|
||
| (Work in Progress) |
There was a problem hiding this comment.
Please reference a tracking bug here as well.
|
As Ryan is currently afk for this week, I talked with Georg and we will go ahead and merge this one (feedback was addressed). |
added docs for real life use cases and profile history