You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide ensures that all documentation for the MathLive and Compute Engine libraries remains consistent, clear, and helpful for its target audience of developers, educators, and scientists.
4
+
5
+
### Tone and Voice
6
+
7
+
The voice of the documentation should be **professional, yet approachable and encouraging**. It should feel like a knowledgeable colleague guiding the reader through the library.
8
+
9
+
***Be Direct and Clear:** Use simple sentence structures and clear language. Avoid jargon where possible, but when technical terms are necessary (e.g., "boxed expression," "lexical scope"), define them or link to their definitions.
10
+
***Use an Inclusive Point of View:**
11
+
* Address the reader directly using the second person ("you"). Example: "You can customize the mathfield..."
12
+
* Use the first-person plural ("we'll") for tutorials and step-by-step guides to create a collaborative feel. Example: "In this tutorial, we'll create a web-based quiz."
13
+
***Be Action-Oriented:** Use imperative verbs for instructions. Start sentences with "To do X, use Y..." to make steps clear and actionable.
14
+
15
+
### Formatting and Structure
16
+
17
+
Consistency in formatting makes the documentation easier to navigate and read.
18
+
19
+
#### Page Structure
20
+
***`<Intro>`:** Every major guide or reference page should begin with an `<Intro>` block. This block provides a concise, high-level summary of the page's content, setting the context for the reader.
21
+
***`<ReadMore>`:** Use this component to link to related topics. This keeps the current page focused while providing pathways for readers who want to dive deeper into a specific area.
22
+
***Example**: ` <ReadMore path="/compute-engine/guides/simplify/">Read more about **Simplifying Expressions**<Icon name="chevron-right-bold" /></ReadMore>`
23
+
24
+
#### Headings
25
+
Use Markdown headings (`#`, `##`, etc.) to create a clear hierarchical structure. Page titles are automatically generated; start with `##` for the main sections within a page.
26
+
27
+
#### Emphasis
28
+
***Bold (`**text**`)**: Use for:
29
+
* Key terms on their first introduction (e.g., **symbolic structure**, **fill-in-the-blank**).
30
+
* UI element labels (e.g., **Copy**, **Undo**).
31
+
* Important notes or warnings within a sentence.
32
+
***Code (`<code>text</code>`)**: Use for:
33
+
* HTML tags: `<math-field>`
34
+
* File names and paths: `/compute-engine/guides/security/`
35
+
* Property and method names: `mf.value`, `.simplify()`
36
+
* Attribute names: `read-only`
37
+
* LaTeX commands in prose: `\placeholder[]{}`
38
+
***Keyboard Keys (`<kbd>key</kbd>`)**: Use for all keyboard key references. Example: <kbd>ALT/OPTION</kbd>+<kbd>SPACE</kbd>.
39
+
40
+
#### Code Blocks
41
+
***Interactive Demos (`live`)**: Use for live, editable examples that showcase the functionality directly on the page.
42
+
````
43
+
```live
44
+
:::html
45
+
<math-field>f(x) = \sin(x+\pi)</math-field>
46
+
```
47
+
````
48
+
* **Static Examples (`js example`, `json example`, etc.)**: Use for non-interactive code snippets that illustrate a concept or API usage.
* **Line Highlighting**: Use `mark-html-line` or `mark-js-line` to draw attention to specific lines in a code block.
55
+
````
56
+
```live show-line-numbers mark-line=4
57
+
````
58
+
59
+
#### Alerts and Callouts
60
+
Use callouts to highlight important information.
61
+
* `:::info[Note]`: For supplementary information, tips, or non-critical notes.
62
+
* `:::warning[Caution]`: For important information that, if ignored, could lead to unexpected behavior, errors, or a poor user experience (e.g., deprecated features, browser quirks).
63
+
* `:::caution`: For high-risk actions or configurations, especially those with security implications (e.g., modifying Content Security Policy).
64
+
65
+
#### Tables
66
+
Use Markdown tables for structured data. For API references and lists of options, use the `symbols-table` class for consistent styling.
67
+
68
+
```html
69
+
<div class="symbols-table first-column-header">
70
+
| CSS Variable | Usage |
71
+
|:---|:---|
72
+
| `--caret-color` | Color of the insertion point |
73
+
</div>
74
+
```
75
+
76
+
#### API Reference Components
77
+
When documenting functions and their signatures, use the provided custom components for consistency.
78
+
* **`<FunctionDefinition>`**: Wraps the entire documentation for a function.
79
+
* **`<Signature>`**: Details a specific function signature, including parameters and return type.
The existing documentation is well-structured and comprehensive. The following suggestions aim to enhance its consistency and clarity further.
5
+
6
+
#### 1. Standardize Reference Page Structure
7
+
The `combinatorics` and `number-theory` reference pages are excellent models. They provide a clear, concise summary for each function before showing the signature and code examples.
8
+
***Suggestion:** Adopt this "summary-first" structure for all API reference pages (e.g., `arithmetic`, `collections`). A short, descriptive paragraph explaining what a function like `Sum` or `Product` does and its real-world use case would be very helpful before diving into its signatures.
9
+
10
+
#### 2. Clarify Distinction Between Callouts
11
+
The usage of `:::warning` and `:::caution` is sometimes interchangeable.
12
+
***Suggestion:** Formalize their use cases as defined in the style guide above:
13
+
*`warning`: For potential errors, unexpected behavior, or things that might not work as a developer expects (e.g., the `file://` protocol limitations).
14
+
*`caution`: Reserve this for higher-stakes issues, especially those related to security (like CSP and Trusted Types) or irreversible actions.
15
+
16
+
#### 3. Enhance Inter-linking
17
+
The use of `<ReadMore>` is effective, but there are opportunities for more granular, in-context linking.
18
+
***Suggestion:** Whenever a technical term from another page is mentioned (e.g., "canonical form," "boxed expression," "MathJSON"), link it directly to its definition page on its first use in an article. This helps readers who may not be reading the documentation sequentially.
19
+
20
+
#### 4. Expand the Tutorials Section
21
+
The "Simple Quiz" tutorial is a fantastic, practical example. Building more of these would significantly improve the learning curve for new users.
22
+
***Suggestion:** Add tutorials covering other common use cases:
23
+
***Building a Scientific Calculator:** A tutorial focused on using `expr.evaluate()` and `expr.N()` with a more complex, customized virtual keyboard.
24
+
***Creating a Dynamic Worksheet:** Showcase how to use `readonly` fields with multiple `\placeholder` prompts and dynamically update the content.
25
+
***Advanced Symbolic Manipulation:** A guide on using `expr.subs()` and `expr.replace()` to build a simple equation solver or expression transformer.
26
+
27
+
#### 5. Be Explicit About "Mathfield" vs. "MathfieldElement"
28
+
The documentation sometimes uses `mathfield` and `MathfieldElement` interchangeably. While context often makes it clear, being explicit can prevent confusion.
29
+
***Suggestion:**
30
+
* Use `<math-field>` when referring to the HTML tag.
31
+
* Use `MathfieldElement` when referring to the JavaScript class or its static properties/methods (`MathfieldElement.computeEngine`).
32
+
* Use "mathfield" (lowercase) as a general term for an instance of the component on a page.
0 commit comments