This page includes our planning schedule for Documentation Office Hours, and also lists our ideas pool for future. Feel free to suggest subjects you’d like to see covered, and share those you’d like to see prioritised.
See our Documentation Office Hours index for the list of previous office hours with direct links to their published recordings.
Schedule
| Date | Presenter(s) | Demo / discussion |
|---|---|---|
| 28/06/24 | Keirthana | Technical Author or Technical Writer |
| 05/07/24 | Robert | AI, a force for good in documentation? |
| 12/07/24 | Keirthana | How-to vs tutorial |
| 19/07/24 | Shane | 10 Ways to Document Terminal Commands |
Future ideas
The structure of the office hours is usually a demo, presentation or discussion followed by a question and answer session.
- Diátaxis related subjects
- Interview of Daniele, including QA from the writers and community
- Understanding Diátaxis
- Documentation workshop; work on a real document live
- How-to vs. a tutorial
- Documenting a new project
- Testing the product, first steps, stages. Inviting contributions
- Start contributing to an open source project
- Understanding how the project works and what they need
- Documentation and design
- API documentation approaches. Swagger, manual, etc.
* Documentation as code
* Pros and cons. Approaches. Docs inside code, externally. How developersmay interact with documentation. - Discussion: AI, a force for good in documentation?
- Should we use it? How could we use it? Do we currently use it?
- Getting feedback
- Various approaches; analytics, comments, issue requests, pop-ups
- Conclusions to draw from feedback
- How to give feedback effectively
- Reducing support cases
- Cost benefit of technical authors and why this may be dangerous
- Demo our editing environments and workflows
* Tips for getting hired as a technical writer or author - How to encourage engineers to write their own documentation
- CMS / Publishing frameworks
- Fight! RST vs. XML vs. Markdown
- On-boarding at Canonical; the challenges of joining a company
- Some of our favourite documentation (Arch, etc.)
- Technical author or technical writer
* Overview of how we edit and publish documentation (Discourse, Sphinx) - GitHub Actions for documentation
- Writing is designing; content design principles and writing
- Recommended books / reading to help with technical writing
- Diagrams: standards, software, syntax, tools, and general approaches