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

Apply technical writing style to the Surge XT manual #348

Open
5 of 12 tasks
j5v opened this issue Mar 17, 2024 · 2 comments · Fixed by #350 or #354
Open
5 of 12 tasks

Apply technical writing style to the Surge XT manual #348

j5v opened this issue Mar 17, 2024 · 2 comments · Fixed by #350 or #354

Comments

@j5v
Copy link
Collaborator

j5v commented Mar 17, 2024

I'd like to apply a writing style to the Surge XT manual, in line with, say Microsoft, GDS, or other style guides.
This does not include changes to the structure of the manual. The meaning of the information remains the same.

Guidance

Ideally, we should:

  • use plain English, using simple words and short sentences, for users whose first language is not English.
  • front-load headings and paragraphs, so users can vertically scan the first words of each line for what they need.
  • use consistent words to describe what the user does with the UI, like "select".
  • use present tense.
  • use active voice.
  • use macOS convention (Sentence Case) for UI labels.
  • display hierarchies of information in a structured way, rather than as multiline paragraphs.
  • use nouns for concepts, verbs for tasks (check whether we can do this without breaking links).

Draft pogress:

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09
  • 10
  • 11
  • 12

Tasks found

Should triage and move to issues:

  • CSS has greedy overrides and some bugs.
  • Patch browser screenshot needs update, to show the Undo UI.
  • Save dialog screenshot needs update, to show "Store tuning in patch"
  • Cross-reference MPE things (Dual/split, Status button, main menu).
  • Some cross-references (in Polyphony limit) should jump more precisely to related content. Use custom anchors, or create lower-level headings.
  • Make "Surge XT is best used..." active.
  • Mark external links with arrow, like Wikipedia does. Shall we force a new tab also?
@j5v
Copy link
Collaborator Author

j5v commented Mar 17, 2024

I'll do this on a fork + branch.

@j5v
Copy link
Collaborator Author

j5v commented Mar 22, 2024

This is still WIP; was auto-closed because there were no remaining linked issues at PR merge.

@j5v j5v reopened this Mar 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment