What solution is used by your institution to document Research Computing Activities?

Discussion Zone
, ,
1

This summary reflects the collective experience and advice of research IT professionals, providing a practical reference for organizations seeking to improve their documentation solutions.

To create a brief report of the document takeaways, I (AI) analyzed the discussion among IT professionals about their documentation solutions, challenges, and best practices. The report synthesizes recurring themes, highlights, and actionable insights, with examples from various institutions to illustrate key points. This approach ensures the summary is both representative and practical for organizations evaluating or improving their documentation platforms.

Brief Report: Documentation Solution Takeaways

1. Popular Documentation Platforms

  • ServiceNow KB: Used for integration with ticketing systems, but often criticized for poor search/browsing experience and high friction in editing.

  • Atlassian Confluence: Common for internal documentation, but issues with Google indexing and content sprawl.

  • MkDocs (with Material theme), Docusaurus, Bookstack, Wiki.js: Favored for user-facing documentation due to markdown support, ease of contribution, version control, and static site generation.

  • GitHub: Used as a backend for documentation, enabling version control and CI/CD automation.

2. Key Features Valued

  • Granular Access Controls: Ability to separate internal, public, and restricted documentation.

  • Ease of Contribution: Markdown-based systems and Git integration lower barriers for team edits and updates.

  • Search and Navigation: Simple, effective search and clear navigation structures (hierarchies, landing pages) are critical for usability.

  • Automation and Integration: Automated page generation, CI/CD pipelines, and integration with ticketing systems streamline maintenance.

  • Accessibility and Compliance: Meeting accessibility standards (e.g., WCAG 2.1 AA) is increasingly required and tools like SiteImprove and WAVE are used for assessment.

3. Common Challenges and Drawbacks

  • Poor Search/Browsing in Ticketing KBs: Users struggle to find information if documentation is only accessible via search, with no hierarchical structure.

  • Content Duplication and Migration Pain: Moving between platforms (e.g., Drupal to ServiceNow) is labor-intensive and risks content fragmentation.

  • Limited Indexing: Some platforms (e.g., ServiceNow, Confluence) do not allow Google indexing, reducing discoverability.

  • Friction in Editing: High effort required to update KB articles can lead to outdated documentation.

  • AI/Automation Risks: Concerns about generative AI tools and data privacy in documentation workflows.

4. Best Practices and Recommendations

  • Democratize Editing: Allow broad team participation in documentation updates.

  • Maintain Clear Structure: Use landing pages, hierarchies, and categorization to aid navigation and discovery.

  • Automate Where Possible: Leverage CI/CD, automated formatting, and data-driven page generation.

  • Monitor and Prune Content: Regularly review and update documentation, using version control and article expiration policies.

  • Retain FAQs and Public Content: FAQs help both users and AI tools; public-facing docs should be indexed for broader benefit.

  • Accessibility First: Ensure documentation meets accessibility standards from the outset.

5. Emerging Trends

  • Agentic AI and Automation: Platforms are moving toward AI-driven ticket triage, resolution drafting, and policy compliance checks.

  • Migration to New Tools: Some teams are considering or moving to newer platforms like Zensical, ProperDocs, and MkDocs-MaterialX for better support and features.

Example Implementation:

  • A research computing group migrated from Confluence to MkDocs on GitHub, enabling markdown editing, automated builds, and Google Analytics. This improved accessibility, reduced support tickets, and made documentation easier to maintain and update.

  • Another team uses ServiceNow for internal docs but maintains a public-facing static site for user guides, ensuring both security and discoverability.

This summary reflects the collective experience and advice of research IT professionals, providing a practical reference for organizations seeking to improve their documentation solutions.

What do you think? Does your institution have a different solution? Please share.