Technical Writing

Illegal Argument

What’s this? Another Illegal Argument episode already? And so close to the last one - it seems the shift to working from home and remote recording has already showed a payoff.

During the last episode, I’d had it in my mind to discuss the need to improve our documentation, and general communication skills that developers, and development teams often overlook. More so now that many organisations are moving into distributed, remote teams - many of which may never return to normal “office life”.

With this in mind, I thought I’d make use of our new remote recording facilities and bring on both Tim McNamara (Vice-President of NZOSS, Canonical Guy, Author of Rust In Action) and Josh Addison (Technical Writer at MYOB, Game Developer, Conspiracy Podcaster) to lend their voices to our argument.

On this episode we cover (or planned, as always - things got sidetracked):

Java News

• JEP 384: Records (Second Preview)
• Why #Java record getters have no 'get' prefix?
• Call for Discussion: New Project: Leyden (static compilation for Java - the return of GCJ?)

Technical Writing

• Why Writing Software Design Documents Matters
• Things Markdown got Wrong
• Writing Test Plans
• Architecture Design Records
• How to write better tickets/commit messages/emails etc. etc.
• Tooling?
  • Asciidoc
  • ProWritingAid, Grammarly
  • Dropbox Paper
  • Vale - cross platform command line style checker
• Question-led docs, e.g. cookbook type
• Doctests are better than you think
• Knowing your audience - differences between "documentation" and "book writing"
• Rust In Action
• WriteTheDocs Slack

Full links to everything discussed and planned to discuss are found over on my raindrop bookmarks.