Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The architecture "overview" seems overly detailed #10

Open
BoCupp-Microsoft opened this issue Feb 12, 2019 · 0 comments
Open

The architecture "overview" seems overly detailed #10

BoCupp-Microsoft opened this issue Feb 12, 2019 · 0 comments

Comments

@BoCupp-Microsoft
Copy link

Consider making the "arcitecture overview" just "architecture" and add an overview between the summary and the architecture section.

I think the overview should contain some principles of your design and the broad brush strokes of how communication happens. I would explain conceptually how TSF works (in lay terms - don't use interface or method names), then state any contraints on the design and invariants that you want to keep so that the design follows from what's presented in this section.

<sample>
Windows Text Services facilitates communication between input methods (handwriting recognition, speech recognition, shape-writing, etc), and editing applications that want text input (code editors, spreadsheets, or rich text editing applications like Microsoft Word). Each editing application has a model for representing the content it edits, and to avoid the need for each input method to code against N different editor document models, Windows Text Services defines an intermediate language to facilitate communication between the editing applications and the input methods: a shared plain-text buffer of content.

The shared buffer is updated cooperatively with the help of Windows Text Services. When an input method delivers input to an editing application, it does so by requesting that Windows Text Services update the shared buffer, and Windows Text Services can in response notify the editing app how the buffer is being modified so that the editing application can update its document model.
...
</sample>

I would expand the above to talk about selection state, layout state, highlighting and modes for input. Say something about why each feature exists so its clear what the code we've written is trying to accomplish... example: "highlighting of text in the buffer can also be requested by an input method so it can, for example, indicate what text is being composed in response to phonetic input. When the input method requests a highlight over the range, Text Services does X and the editing app is responsible for Y."

After that if you can include some constraints, principles, invariants and key assumptions of the design and I think that will make the transition from summary to architecture will go smoothly...

<examples>
Constraint: Windows Text Services has evolved with various Windows releases. Our goal is to provide support back to Windows 7. TSF1 is available back to (insert version) and will be used to access the text input services of the Windows platform on Windows 7 and above.

Constraint and applicable Principle: TSF1 requires a synchronous response to queries about the state of the shared buffer, yet the input thread of the browser process must remain responsive. To acheive both requirements, no blocking cross-process calls or waiting for script to yield so the state of the DOM can be read will be allowed; instead all queries must be fulfilled from cached state maintained in the browser process that mirrors (with some imperceptible delay) the contents of the DOM in the renderer process.

Principle: Since both input methods and editing applications are trying to update the same editable content, conflicts can occur. To resolve conflicts, the order of operations as seen by the DOM will be considered authoritative.

Key assumption: The view of the editable content provided to Windows Text Services should be aligned with what the user sees on the screen. Transient state of the DOM that the user cannot see is irrelevant to the editing process and the view provided of the editable content to Windows Text Services.

Key assumption: We are free to reuse TSF objects that describe the content of an editable region of an editing app as there is no known data cached using the identity of these objects, i.e. all that is necessary to facilitate a great editing experience can be computed from the contents of the DOM and populated into an appropriate TSF object as focus shifts from one editable element to another.

...
</examples>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant