Introduction to ICS Documentation System
Well-crafted documentation is crucial for the success of any team. It ensures that your products and services are accessible, understandable, and usable by your target audience. Documentation serves as a roadmap for new users, a reference for existing users, and a guide for contributors. It enhances the user experience and facilitates smoother project development and maintenance.
We have built a documentation platform to provide a robust foundation for ICS knowledge to be captured. This system is based around the concept of FAIR documentation, which states that documentation should be Findable, Accessible, Interoperable, and Reusable. To achieve these goals, we leveraged well vetted tools such as the Divio Documentation System, the Markdown standard, and git version control.
What is the Divio Documentation System
The Divio Documentation System is a structured approach to creating and organizing documentation. It divides documentation into four distinct quadrants: Tutorials, How-to Guides, Explanation, and Reference. This system aims to cater to different user needs efficiently, whether they are looking for a step-by-step guide, a quick solution, detailed understanding, or specific technical details.
Why Choose Markdown for Documentation
Markdown is a lightweight markup language with plain text formatting syntax. It's designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is widely used in documentation for several reasons:
- Simplicity and Readability: Markdown's syntax is straightforward, making it easy for writers to focus on content rather than formatting.
- Portability: Being a plain text format, Markdown files are platform-independent and can be easily shared, edited, and managed across different systems and version control platforms.
- Flexibility: Markdown can be easily converted to various output formats, such as HTML, PDF, and Word documents, making it versatile for different documentation needs.
- Tool Support: Many tools and editors, including Visual Studio Code (VS Code), support Markdown natively, providing features like preview, linting, and extensions to enhance productivity.
Git Version Control
Most members of ICS have or will use Git on a regular basis for managing assets related to their work. This could be Jupyter notebooks, Terraform scripts, or web application code. Git tooling should be familiar to most team members. Those members that are not as familiar with Git will be able to use tools like Obsidian to help make Git more approachable. However, since Git is so universally used, there are many existing tools to choose from.
Implementation Strategy
Effectively managing documentation requires integrating it seamlessly into our daily workflows. Using familiar tools and platforms like VSCode or Databricks, streamlines the process of managing our daily tasks, and managing documentation, ensuring a cohesive workflow. Standardized tools and templates guarantee consistency across documents, while fostering collaboration among team members enriches our knowledge base with diverse insights.
Differentiating between project-specific notes and broader team-focused documentation is essential. Project notes are kept in individual notebooks, while general documentation is stored in a shared repository, serving both as an internal resource and the foundation for an internal documentation website. Documents deemed valuable for external audiences are tagged for public sharing, enhancing transparency and client engagement.
Quality Assurance
Quality assurance for documentation is a continuous, team-wide effort. Regular reviews ensure the information remains current and relevant, while incorporating peer review and user feedback enhances usability and effectiveness. Adopting code development practices, such as using pull requests for documentation changes, promotes accountability and maintains high standards. This structured approach, coupled with cross-team collaboration, ensures our documentation is of high quality and satisfies the needs of our team and our clients.
Conclusion
Effective documentation is vital for the success and reliability of services provided by ICS teams to the medical school. Adopting this approach to documentation offers a structured and comprehensive process to creating documentation that effectively shares knowledge within ICS and with our clients, enhancing collaboration and an informed user base.