Summary

Let's document how Mongoid works. We can do it incrementally, and over time build up a corpus of documentation that can act as a kind of specification for Mongoid.

Motivation

Mongoid is a complicated piece of software, with a lot of different moving parts that were contributed to and maintained by a number of different developers over the years, with differing levels of experience and differing opinions. This has resulted in a system that is difficult to understand.

The practical implications of this include:

1. Mongoid is challenging for newcomers to the code base to understand. It's challenging even for the experienced engineers to understand in its entirety. Becoming a "Mongoid Expert" is a challenge.
2. The difference between "bug" and "works as designed" can be gray at times, which can lead to "fixing" something that shouldn't actually have been fixed.
3. Architectural decisions are spread across numerous archived Jira tickets, or lost to Slack purges.

Who is the affected end user?

This documentation is intended primarily for our own internal use, but could certainly be useful to other developers who wish to contribute to Mongoid.

How does this affect the end user?

There is no immediate affect on end users, though eventually the documentation could be used to inform bug fixes and features that would affect them.

How likely is it that this problem or use case will occur?

Frequently.

If the problem does occur, what are the consequences and how severe are they?

We encounter issues regularly that we need to investigate and evaluate, and more and more time is spent just digging into Mongoid and learning/remembering why it works the way it does. Having some documentation that describes the expected behavior of different subsystems, and how the systems work together, would save a lot of time.

Is this issue urgent?

Not urgent. This is basically a new feature.

Is this ticket required by a downstream team?

No.

Is this ticket only for tests?

No.

Cast of Characters

Engineering Lead:
Document Author:
POCers:
Product Owner:
Program Manager:
Stakeholders:

Channels & Docs

Slack Channel

[Scope Document|some.url]

[Technical Design Document|some.url]