Technical Writing


Fetch error

Hmmm there seems to be a problem fetching this series right now. Last successful fetch was on October 13, 2022 15:51 (5M ago)

What now? This series will be checked again in the next day. If you believe it should be working, please verify the publisher's feed link below is valid and includes actual episode links. You can contact support to request the feed be immediately fetched.

Manage episode 262185674 series 49589
By Mark Derricutt, Greg Amer, and Richard Vowles. Discovered by Player FM and our community — copyright is owned by the publisher, not Player FM, and audio is streamed directly from their servers. Hit the Subscribe button to track updates in Player FM, or paste the feed URL into other podcast apps.

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.

140 episodes