Read the Docs: Best Practices for Site Documentation (BoF)¶
Sites provide sophisticated technical solutions and services that require a high level of technical competence to use. Technical user-facing documentation is an essential part of these services, however the time and skills required to write and maintain quality documentation are easy to underestimate for both technical staff and management.
The documentation at some sites has been developed bottom-up by engineers trying to address the needs of users. This BoF will foster an exchange of best practices and ideas for user-facing documentation, based on the experiences of these engineers who maintain documentation infrastructure and write the documentation.
| time | activity |
|---|---|
| 3:15 | introduction and invitation for audience submissions |
| 3:20 | site presentations |
| 4:00 | panel and show and tell |
| 4:30 | finish |
Audience participation¶
Submit examples via the Doc Submissions page — no account needed, all submissions are publicly visible.
Submit examples of your favourite from your site's documentation
- examples of great docs;
- examples of docs with an interesting story behind them;
- here be dragons: docs that are not so great.
- don't be shy - maybe somebody in the room has faced similar challenges.
During the panel, we will view some of the audience, and the person who nominated them will have the opportunity to tell everybody:
- The story behind how the documentation was created.
- Why the documentation is good or problematic for your site.
- Any other insights you want to share.
Not only your site's docs
Examples of documentation from the that you enjoy using, or fear entering, are also welcome.
Maybe there is something that inspired your own docs, or showed you what to avoid!
Site Presentations¶
Sites who volunteered will give up to 8 minute presentations about their user facing documenation.
- ORNL: Chris Fuson
- CSCS: Ben Cumming
- EEPCC: Juan Herrera
- CINES: Cedric Jourdain
- Bristol: Richard Gilham
In order to keep the conversation focussed, choose two or more of the following topics:
- Show and tell one part of your documentation that you are particularly proud of.
- Which framework do you use for documentation deployment (CMS or docs-as-code)?
- How do you organise documentation to make information discoverable by users and maintainable by writers.
- How is responsibility distributed?
- e.g. is there a core documentation team that perform writing/editing services?
- e.g. is the workload distributed over all engineering teams?
- Have we been able to get contributions from the user community?
- Lessons learnt implementing LLM based chatbot services for users.
Panel Discussion with Show and Tell¶
After the presentations, we will have a panel discussion.
- questions from the audience (to the panel, and to the rest of the audience)
- comments and opinions from the audience
- review the audience submissions