ICS Documentation Training Sessions

Session 1: Markdown Fundamentals & Tooling

Introduction to Markdown:
- Overview of Markdown and its benefits.
- Basic syntax elements (headings, lists, links, images, tables, etc.).
Markdown Editing Tools:
- Demonstration of editors (e.g., VSCode, Databricks, Obsidian).
- Pros and cons of each tool.
- How to configure editors for an optimal Markdown experience.
Best Practices for Markdown:
- Writing clear, maintainable documentation.
- Tips for consistency across documents.
Interactive Component:
- Short hands-on exercise editing a sample document.
- Q&A and discussion on preferred tooling.

Objectives:
- Develop a clear, navigation-friendly structure for internal documentation.
- Learn strategies to enhance the discoverability and navigability of content.
Outline:
- Content Organization Principles:
  - Importance of a consistent structure.
  - Techniques for categorizing and tagging content.
- Information Architecture:
  - Creating an effective navigation system.
  - Defined sections and subsections.
  - Implementing metadata and search-friendly features.
- Case Studies/Examples:
  - Review of Divio/Diátaxis documentation framework
- Interactive Component:
  - Group activity discuss current documentation and how it fits the defined structure or not.

Objectives:
- Establish standard operating procedures for creating and maintaining documentation.
- Create guidelines that ensure consistency and quality.
Outline:
- Documentation Lifecycle:
  - Steps from creation to review, approval, and updates.
  - Handling versioning and revisions.
- Developing Style Guides:
  - Elements to include in a documentation style guide.
  - Templates and standardized formats.
- Review and Approval Process:
  - Strategies for peer reviews and collaborative editing.
  - Tools and techniques for feedback management.
- Interactive Component:
  - Open discussion on potential process improvements.
  - Drafting a basic process flowchart together.

who needs to review and what sections?
- community available content should be reviewed
- documents that outline support steps for cross training
  - have a team mate verify the instructions
meeting notes, high level project notes
- does not require review
multi-team projects
- reviewed by others involved in the project
Use PRs as needed to review general docs
Can use PRs and self approve for consistent workflow
Allow check in to main for things like meeting notes
TODO: create guidance on when to request a review

Objectives:
- Foster a collaborative culture around documentation.
- Ensure continuous quality improvement through regular feedback loops.
Outline:
- Collaborative Tools and Platforms:
  - Tools to facilitate teamwork (e.g., pull requests, inline commenting).
  - Best practices for managing collaborative workflows.
- Review Mechanisms:
  - Setting up regular review cycles.
  - How to incorporate peer feedback effectively.
- Feedback Loops & Iteration:
  - Strategies for ongoing documentation improvement.
  - Measuring documentation quality and user satisfaction.
- Interactive Component:
  - Group discussion on challenges and solutions in collaborative documentation.
  - Scenario-based workshop on resolving common review issues.

Objectives:
- Understand how markdown documentation is transformed into website content.
- Explore tools and processes that bridge the gap between documentation and web presentation.
Outline:
- From Markdown to Website:
  - Overview of static site generators and other build tools.
  - How content management workflows integrate with web publishing.
- Tooling and Automation:
  - Demonstrating tools for syncing repositories with websites.
  - Best practices for automation and continuous integration.
- Design & User Experience:
  - How documentation structure affects website navigation and usability.
  - Examples of effective documentation-powered sites.
- Interactive Component:
  - Live demo of a build process from markdown to website preview.
  - Discussion on customization and branding.

Objectives:
- Apply the concepts from previous sessions in a practical, collaborative environment.
- Gather real-time feedback to refine processes and workflows.
Outline:
- Interactive Exercises:
  - Simulated tasks covering Markdown editing, repository management, and site integration.
  - Breakout sessions to work on sample projects.
- Group Collaboration:
  - Teams present their approaches and receive feedback.
  - Open forum for discussing challenges and ideas.
- Feedback Collection:
  - Structured discussion on what worked and areas for improvement.
  - Setting action items and next steps for ongoing documentation improvement.
- Wrap-Up:
  - Summarize key learnings from the series.
  - Outline follow-up sessions or support mechanisms for continued improvement.