1329840 - Build Comprehensive Data Documentation

Status: RESOLVED DUPLICATE of bug 1341617

(Data Platform and Tools :: Documentation and Knowledge Repo (RTMO), defect, P1)

Description

[Ryan Harter [:harter]]

Telemetry documentation is difficult to digest.
We've had some recent improvements, but we still have a ways to go.
I want to take another pass at fixing this in 2017. 

Some issues:
* Documentation is frequently out of date
  * Dead links in the wiki
  * Stale content
* Documentation is poorly organized, difficult to discover
  * It's spread across different platforms (wiki.mo, github, readthedocs, ...)
  * There's no clear path for digesting the provided information
    * There's no sense of importance or context, everything is a web
    * Ideally, we'd have tutorials where a new analyst could learn 
      about a data source, e.g. intro to telemetry
  * There's a lot of confusion about where to store documentation
* Documentation is primarily for developers
  * Some documentation is effectively, "read the code", which isn't useful for
    new users or analysts
  * Documentation focuses on how the data is generated, not necessarily how it
    should be used

Comment 1

[Ryan Harter [:harter]]

I plan on sitting down with the team to identify some clear goals for the next documentation reboot. Look out for an update later this week.

Comment 2

[Ryan Harter [:harter]]

Updating this thread, I'm working on an outline of our documentation needs in the "outline" brance [2] of this repository [1]. I hope to have something to get feedback on by next week. For now, I'm using the gitbook toolchain but that's easy enough to change later.

[1] https://github.com/harterrt/telemetry-docs
[2] https://github.com/harterrt/telemetry-docs/tree/outline

Comment 4

[Ryan Harter [:harter]]

I've drafted some Q1 goals for this effort [1]. Rob, do you mind taking a look?

[1] https://docs.google.com/document/d/1YuNKWV13mIIaSBngS_wx6N_J1XRGcGOG38O9_EXNI64/edit#heading=h.tgwgayfpzblp

Comment 5

[Rob Miller [:rmiller]]

I think your plan looks like a good start, thanks Ryan! Two thoughts come to mind:

* Having goals is great, but we're being encouraged to frame our efforts in terms of OKRs, so it might be a good idea to take a stab at that. This would include a) looking at the Firefox-wide OKRs and identifying which of them this effort supports and b) reframing the Q1 / Q2 goals into an OKR format that we can put on a project page for reporting up and out.

* You've got "Identify documentation yet to be written and find owners..." under the "Transition to the new platform" stretch goal. I agree that getting all of the docs migrated to a new platform should be a stretch goal, but I think it's a good idea to create an inventory of all of the docs we want to have along w a way of tracking which ones exist (and where) should be higher up on the priority list.

Comment 6

[Ryan Harter [:harter]]

(In reply to Rob Miller [:RaFromBRC :rmiller] from comment #5)
> I think your plan looks like a good start, thanks Ryan! Two thoughts come to
> mind:
> 
> * Having goals is great, but we're being encouraged to frame our efforts in
> terms of OKRs, so it might be a good idea to take a stab at that. This would
> include a) looking at the Firefox-wide OKRs and identifying which of them
> this effort supports and b) reframing the Q1 / Q2 goals into an OKR format
> that we can put on a project page for reporting up and out.

These goals seem like good Key Results, so I added a clear objective statement. This project clearly lines up with the 2017 Data Platform Documentation OKR. Thomas mentioned the project reporting templates in today's meeting, so I expect to sync with him sometime soon to get this into the new format. 

> * You've got "Identify documentation yet to be written and find owners..."
> under the "Transition to the new platform" stretch goal. I agree that
> getting all of the docs migrated to a new platform should be a stretch goal,
> but I think it's a good idea to create an inventory of all of the docs we
> want to have along w a way of tracking which ones exist (and where) should
> be higher up on the priority list.

Good call. I moved these two key results higher up the list.

Comment 7

[Ryan Harter [:harter]]

FYI, I'm moving this work to a Mozilla owned repository here:
https://github.com/mozilla/firefox-data-docs.

The outline is pretty stable at this point. Next steps are identifying documentation that still needs to be written, filing bug, and finding owners. Look out for bugs next week.

Comment 8

[Ryan Harter [:harter]]

Closing this bug out since we're tracking progress in the meta bug:

https://bugzilla.mozilla.org/show_bug.cgi?id=1341617