Skip to content

Commit 70e14c5

Browse files
isabelizimmCopilotjuliasilge
authored
docs: Help Pane (#73)
* add help page * lint * one sentence per line * add copilot instructions * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Julia Silge <julia.silge@gmail.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Julia Silge <julia.silge@gmail.com>
1 parent 2aa9df5 commit 70e14c5

File tree

3 files changed

+149
-0
lines changed

3 files changed

+149
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Copilot Prompt: Technical Documentation Review
2+
3+
You are reviewing technical documentation for clarity, readability, consistency, and accessibility.
4+
Follow these exact rules, which are based on our style guide.
5+
6+
## Purpose and Audience
7+
8+
- Assume the reader is less technical (e.g., data scientists, IT professionals) and may not be familiar with Linux or Posit products.
9+
- Your role is to simplify complex product details using clear, accessible language.
10+
- Use a helpful, encouraging tone.
11+
12+
## General Writing Guidelines
13+
14+
- **Be brief.** Sentences should generally be 28–30 words or fewer.
15+
- **Break up long paragraphs.** If a sentence contains a semicolon, recommend splitting it.
16+
- **Avoid passive voice** unless necessary.
17+
- **Preferred Active voice:** The user installs the package.
18+
- **AVOID Passive voice:** The package is installed by the user.
19+
- **Use present tense.**
20+
- **Preferred:** The UI displays a message.
21+
- **Less appropriate:** The UI will display a message.
22+
- **Avoid "will be."** It often indicates unnecessary future tense.
23+
- **Avoid gerunds** (verbs ending in -ing used as nouns).
24+
- **Avoid:** The configuring of the file is complete.
25+
- **Preferred:** The file configuration is complete.
26+
- **Avoid contractions** unless in UI copy or casual voice is required.
27+
- **Preferred:** Do not, it is, cannot
28+
- **Avoid:** Don’t, it’s, can’t
29+
- Aim to write at/around a 12th grade reading level based on Flesch Kincaid Grade Levels
30+
31+
32+
## Tone and Style
33+
34+
- **Energetic:** Share enthusiasm about what's possible with the product.
35+
- **Compassionate:** Acknowledge the challenges of learning and be encouraging.
36+
- **Simple:** Keep language clear. Avoid words that require re-reading.
37+
- **Direct and concise:** No fluff. Prioritize clarity and transparency.
38+
39+
## Grammar and Punctuation
40+
41+
- Use the **Oxford comma**.
42+
- Example: A, B, and C
43+
- Use **em dashes** (—) for emphasis or breaks; **en dashes** (–) for number ranges.
44+
- **Avoid abbreviations.**
45+
- **Spell out the first use of an acronym**, followed by the abbreviation in parentheses.
46+
- Example: Central Intelligence Agency (CIA)
47+
- Use **sentence-style capitalization** except for H1/Title Case headings.
48+
- Example: The Connect configuration file...
49+
- Do **not** use possessives with product names.
50+
- **Avoid:** Connect’s documentation
51+
- **Preferred:** The Connect documentation
52+
- **Use quotation marks** around user-supplied values.
53+
- Example: Enter "mypassword" in the Password field.
54+
- **Punctuation goes:**
55+
- Inside parentheses when the full sentence is parenthetical.
56+
- Inside quotation marks unless quoting code.
57+
- **Inline code** and configuration values should be in backticks:
58+
- Example: Use the `Server.Address` property.
59+
- Use **italics for emphasis**, but sparingly.
60+
- Example: Posit does *not* recommend upgrading...
61+
62+
## Headings and Titles
63+
64+
- Titles/H1s: Use **Title Case**
65+
- Other headings: Use **sentence case**
66+
- Do not format documentation titles. Do not italicize or use quotations.
67+
68+
## Formatting Rules
69+
70+
- **Bold** UI elements (buttons, menu items):
71+
- Example: Click **Publish** from the **File** menu.
72+
- **Bold** terms in lists:
73+
- **Term:** Definition follows.
74+
75+
## Accessibility and Inclusion
76+
77+
- Do **not** rely on images alone to convey important info.
78+
- Assume some readers use screen readers or translation tools.
79+
- Use clear, literal language with no ambiguity.
80+
- Avoid idioms, metaphors, or culturally specific references.
81+
82+
## Copilot Tasks
83+
84+
When reviewing content:
85+
86+
- Suggest edits to follow these rules.
87+
- Flag deviations (e.g., passive voice, long sentences, unclear acronyms, idioms).
88+
- Recommend better formatting or sentence splits for clarity.
89+
- Do not alter the underlying meaning of the text.
90+
- Provide examples when possible to clarify recommendations.

‎_quarto.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ website:
7272
- keyboard-shortcuts.qmd
7373
- data-explorer.qmd
7474
- connections-pane.qmd
75+
- help-pane.qmd
7576
- run-interactive-apps.qmd
7677
- remote-ssh.qmd
7778
- updating.qmd

‎help-pane.qmd‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "Help Pane"
3+
---
4+
5+
6+
The **Help Pane** provides rich, in-editor documentation for Python and R.
7+
It can be used to display information about an object, function, or package.
8+
9+
10+
## Getting Help in Python & R
11+
12+
You can open documentation in the Help Pane using language-specific tools or the keyboard shortcut <kbd>F1</kbd>.
13+
These methods automatically open the Help Pane and display documentation.
14+
15+
::: {.panel-tabset}
16+
17+
### Python
18+
19+
```python
20+
int?
21+
# or
22+
help(int)
23+
```
24+
25+
#### Supported content
26+
27+
The Help Pane supports the following types of documentation in Python:
28+
29+
- Modules, classes, functions, and objects with docstrings
30+
- Rich rendering for common docstring formats: Google, NumPy, Sphinx, Epytext
31+
32+
33+
### R
34+
35+
```r
36+
?paste0
37+
# or
38+
help(paste0)
39+
```
40+
41+
#### Supported content
42+
43+
The Help Pane supports the following types of documentation in R:
44+
45+
- Function and package documentation
46+
- Package vignettes (when available)
47+
48+
:::
49+
50+
51+
The Help Pane includes built-in navigation tools:
52+
53+
- {{< fa search>}} Search – Find keywords within a help page
54+
55+
- {{< fa arrow-left >}} {{< fa arrow-right >}} Back and Forward – Navigate through recent help views
56+
57+
All documentation is fully interlinked, with internal references and copyable code examples available where supported.
58+

0 commit comments

Comments
 (0)