Skip to content

Sat -> Sun, 9-10 May

Situation

Most of my texts weren't meeting the requirements.. or I thought the results were not trackable. I wanted to practice and needed the tool to understand the structure and the guides for writing documentation in the style of Ableton.

Task

I owned it and analized that day from 15-17:00 the rules of writing documentation and the difference in format for the Manual, Release Notes and Bug Fixes. Task was to understand their underlying system to writing documentation and predict their guidelines. Added the notes from Ania and Lars after the interview.

Action

Build a custom CLI application, since Git, runs from what I remembered mainly in CLI and I wanted to get even more confortable to terminal control. Exercised and got result that either my text was too long or too short (concisevness), i was unintentinally using passive voice, or that sometimes I still write in british english. I, also, update my mock-up website since I realized it needed a better structure to fit my current findings: bullet points were use only for bug fixes.

Result

Created a cleaner mock-up and had now the tools to keep improving. I now had some guidelines to work with: 1. American English — No British spellings (colour → color, grey → gray, programme → program, etc.) 2. No marketing language — No exciting, powerful, innovative, seamless, revolutionary, game-changing, etc. 3. User-facing language — No developer jargon (implemented, refactored, backend, API call, hotfix, deprecated, etc.) 4. Do not start with I/We — Lead with the subject, the feature, or the action. 5. UI element capitalisation — Named UI elements are proper nouns (Arrangement View, Group Track, Auto Filter, Correction, Formant, etc.) 6. Acronym capitalisation — MIDI, MPE, CPU, GPU, VST, AU, AAX, DAW, LFO, ADSR, OSC are always all-caps. 7. No contractions — Use full forms: don't → do not, can't → cannot, it's → it is, etc. 8. Software name capitalisation — Live (the software) and version refs like Live 12 are always capitalised. 9. Grammar: allows/enables to — allows to and enables to are grammatically wrong. Use allows you to or lets you. 10. Paragraph length — Max 4 sentences per paragraph. (Not enforced in Free mode) 11. Passive voice — Avoid was added, has been updated, can be accessed. Use active voice. 12. Bug fix structure (Bug Fix mode) — Must describe both: what broke AND what now works. 13. Release note structure (Release Note mode) — Must lead with what the user can now DO. 14. Minimize words — Cut simply, just, easily, obviously, of course, clearly — they make tasks sound trivial. 15. Weak sentence opener — Avoid starting sentences with There is/are or It is. Lead with the real subject. 16. Redundant phrasing — in order to → to, due to the fact that → because, at this point in time → now, etc. 17. Filler phrases — Cut please note, note that, it is worth noting, as you can see, etc. 18. Double spaces — Single space between words and after punctuation. 19. Trailing ellipsis — ... at the end of a sentence implies an unfinished thought. 20. Avoid etc. — Complete the list or write and

Next-Steps

  • ▢ Create a full release notes page for Live 12.4 with all new feature, improvements, and bug fix notes in the same structure as Ableton's official release notes page. This includes formatting according to all linter rules and no exceptions allowed.
  • ▢ Include a before and after section on the documentation website. This includes one of the original stem separation release note changes from round one and one corrected with Ania's changes. Be sure to clearly label this section.
  • ▢ Linter every piece of writing I produce and include an analysis in the daily STAR report of what was found, how it was fixed, and what was learned.
  • ▢ Create a one page introduction to the writing style guide. Why we write for users, why we use active voice, why we use American English, why we be concise. How we got here and why.
  • ▢ Create a full linter README file as proper documentation, including all installation steps, all rules and what they check for, examples and corrected code. This can be used as a documentation sample during the interview process.