Skip to content

Start a style guide for the User Guide#13916

Merged
seanbudd merged 11 commits into
masterfrom
addUserGuideStyleDocs
Jul 22, 2022
Merged

Start a style guide for the User Guide#13916
seanbudd merged 11 commits into
masterfrom
addUserGuideStyleDocs

Conversation

@seanbudd

@seanbudd seanbudd commented Jul 18, 2022

Copy link
Copy Markdown
Member

Link to issue number:

N/A

Summary of the issue:

There is no set of standards or guide when writing documentation for the "User Guide".

Description of user facing changes

The intended audience for this PR is NVDA contributors.
NVDA developers now have suggested formatting for key commands and feature flags.

Feature flag documentation suggests using definition lists.
The default CSS formatting for definition lists is not ideal, the term and definition are listed on separate lines. There is no text formatting, the only indication that a term is linked to a definition is an indentation in front of the term.

This is an example of default formatting:
image

Example of new formatting, where all text is smaller and italicised, terms are bold and definitions are on the same line as the term.
FireFox/Chrome:
image
Mobile:
image

Description of development approach

Created a style guide document

Testing strategy:

Tested rendering the user guide with #13131

Known issues with pull request:

Change log entries:

Code Review Checklist:

  • Pull Request description:
    • description is up to date
    • change log entries
  • Testing:
    • Unit tests
    • System (end to end) tests
    • Manual testing
  • API is compatible with existing add-ons.
  • Documentation:
    • User Documentation
    • Developer / Technical Documentation
    • Context sensitive help for GUI changes
  • UX of all users considered:
    • Speech
    • Braille
    • Low Vision
    • Different web browsers
    • Localization in other languages / culture than English

@seanbudd seanbudd requested a review from a team as a code owner July 18, 2022 03:20
@seanbudd seanbudd requested a review from feerrenrut July 18, 2022 03:20
@seanbudd seanbudd requested a review from Qchristensen July 18, 2022 06:19
Comment thread devDocs/userGuideStandards.md Outdated

@Qchristensen Qchristensen left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work Sean!

Comment thread devDocs/userGuideStandards.md Outdated
Comment thread devDocs/userGuideStandards.md
Comment thread devDocs/userGuideStandards.md Outdated
@seanbudd seanbudd added this to the 2022.3 milestone Jul 20, 2022
@seanbudd seanbudd added the release/blocking this issue blocks the milestone release label Jul 20, 2022
@seanbudd seanbudd requested a review from feerrenrut July 20, 2022 02:09
@AppVeyorBot

Copy link
Copy Markdown

See test results for failed build of commit a50d9472b2

@seanbudd seanbudd merged commit a7507ba into master Jul 22, 2022
@seanbudd seanbudd deleted the addUserGuideStyleDocs branch July 22, 2022 06:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release/blocking this issue blocks the milestone release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants