Documentation Co-Creation with GitHub

Intended Audience

Development teams with minimal or no user assistance (UA) support are the main target group of these guidelines.

Prerequisites

• Your product falls within the scope of use cases for using GitHub as a content source system. For a detailed list of use cases and criteria, see When to Use GitHub as Content Source System | SAP Help Portal.

• You have ensured project staffing. Within the scope of your documentation co-creation project, appoint at least one member of your project team for each of the following personas:

  • UA - a dedicated UA developer or UA consultant supporting multiple teams that have no dedicated UA support.
  • Subject matter expert (SME) - a developer, product owner, architect, partner consultant, or, in general, someone who has technical expertise and knowledge for the product.

Planning

Roadmap Integration (UA, SME)

• Include documentation planning in regular team roadmap and sprint planning sessions.
• Use a service guide template to identify required documentation components for each service/product. For more info, see the SAP Service Guide Template and Simplified Service Guide.

Prioritization (UA, SME)

Prioritize documentation tasks alongside development work to ensure documentation is delivered in sync with product releases. For information on documentation’s legal aspects, see "Documentation" as a Legal Concept.

Infrastructure Setup

Repository Creation (UA, SME)

1. Set up a dedicated documentation repository in your team’s GitHub organization. (UA, SME)

2. Configure the repository to be used as a content source for building and publishing documentation to the SAP Help Portal. For more information, see Setting Up a GitHub Repository to Push Content from GitHub to UACP | SAP Help Portal. (UA)

3. If you’re planning to maintain multiple documentation versions at the same time:

   1. Create a branch for each version.

   2. Add a SAPDocsFile.yaml to each branch and adjust it accordingly. A build is only triggered if the branch specified in the SAPDocsFile.yaml is the same as the branch on which this file is located.

   3. Adjust the version for the documentation in each SAPDocsFile.yaml so that it reflects the specific product version and is unique within the repository. This will ensure that you can see the following:

      • Different builds in the Builds Dashboard for the different versions.
      • Different deliverables in the Deliverables Dashboard for the different versions.
      • A version selector in the output on the SAP Help Portal.

4. Test and ensure that every commit triggers an automated build on UACP that results in a documentation draft published to the SAP Help Portal: (UA)

   1. Push content to the documentation repository.
   2. Check build status in the Builds Dashboard.
   3. Chek deliverable status in the Deliverables Dashboard.
   4. Verify that the deliverable renders correctly on the SAP Help Portal.

Exporting existing documentation sets from IXIA CCMS to GitHub

1. Add the dita-git-serviceuser to your repository with Write access.
2. In the IXIA CCMS, add a delivery channel that points to your repository.
3. Create an output with the output type markdown.sapsimple.
4. Make sure that a toc.yaml file is generated during the export.
5. Add deliverable owners in the SAPDocsFile.yaml file.
6. Disable the previously configured output in the IXIA CCMS.

Pay special attention to the attribute for the ID of the structure in the toc.yaml file. This attribute is called loio. You produced the content of this structure from the IXIA CCMS in the past and now want to set it up in GitHub instead. Make sure that you use the same value for the loio attribute as the one you had before for the related buildable map LOIO in the IXIA CCMS. This is required by UACP to be able to seamlessly continue to display the output of this structure and its content.

For more details on how to export existing documentation from IXIA CCMS to GitHub, see Documentation Written on GitHub - BTPX HANA Product Design - Wiki@SAP.

Repository Administration (UA, SME)

• Nominate a repository administrator. (UA, SME)
  
  Responsibilities of the repository administrator are as follows:

  • Create admin and collaborator teams.
  • Assign roles to the teams.
  • Add/remove users from the teams.
  • Create new issues.
  • Assign existing issues.
  • Assign labels to issues.
  • Close completed issues.
  • Organize project board(s).
  • Create GitHub actions to automate manual activities.

Access and Contribution Process (UA, SME)

• Define contributor roles (e.g., SME to provide technical input, UA, reviewer, or automation).
• Document and communicate the process for submitting, reviewing, and publishing documentation changes for contributors.

Create Drafts

Raw Drafts (SME)

• SME is responsible for creating initial documentation drafts in the repository.

• Drafts must adhere to the following requirements:

  • Follow the SAP Style Guide for Technical Communication. For basic standards overview, see Language and Grammar.
  • Use the agreed markdown flavor and structure. For more details on markdown syntax, see Markdown Guidelines for Co-Creation Projects at SAP.
  • Include technical details, code samples, and code sample explanations for review.

Templates and Examples (UA)

Provide templates and sample documents to guide SME in structuring their drafts.

Testing

End-to-end testing (SME)

• Test the documentation by following instructions as an end user would:

  • Test on a different machine.
  • Test with a different account.
  • Ask a colleague who’s not familiar with the product/service to test.

• Flag unclear instructions or inconsistencies.

• Clarify technical details and resolve ambiguities.

• Employ AI, scripts, or tools to simulate end-to-end walkthroughs of documentation steps, identifying potential issues.

Iterative improvement (SME)

• Incorporate feedback and iterate on the draft to improve accuracy and clarity.
• Review flagged issues, clarify ambiguities, and iterate on the draft, especially in case where UA support is missing.

Review

Language and Style (SME)

Ensure SAP Style Guide adherence. Use existing UA tools, automation, and AI where possible to:

• Suggest language, tone, and terminology improvements.
• Check for consistency.
• Review drafts for markdown syntax, structure, and required frontmatter metadata.
• Split or restructure long/complex documents.
• Adapt drafts as needed to meet publishing requirements.

Acrolinx

Acrolinx examines your content regarding tone, terminology, style, spelling, and grammar and helps you improve your texts by indicating problems and suggesting solutions.

To configure Acrolinx for VS Code:

1. In VS Code, navigate to the Extensions tab on the left and search for Acrolinx for Visual Studio Code.
2. Install the Acrolinx for Visual Studio Code extension and restart VS Code.
3. Once installed, the Acrolinx sidebar is available within VS Code. Configuration steps are identical for both Acrolinx for Visual Studio Code and Acrolinx for IXIA CCMS Web. Follow Configuring Acrolinx in IXIA CCMS Web for detailed instructions.
4. You’re now set up to check your markdown source with Acrolinx. For more information on using Acrolinx, see Using Acrolinx for Finding Content Issues and Keyword Research (SEO).

UAi booster

The UAi Booster is a prototype that provides AI-based authoring support. Within the context of documentation, it helps you brainstorm and speed up your daily tasks with the assistance of large language models (LLMs). Access it directly at https://help.sap.com/uaibooster. For more details on capabilities and how to use it, see UAi Booster.

Technical Review (SME)

• After all changes are made, perform a technical review again to validate accuracy and completeness of the updated documentation.
• Incorporate changes into the final draft.

Copy-Editing

Quality Review (UA)

• Perform a deep edit for language, clarity, consistency,
• Submit documentation for peer review (by another UA or) through a Quality Review Cycle (QRC).
  • Alternatively, use AI to simulate peer review, providing feedback on clarity, completeness, and structure.
• Incorporate feedback from peer reviews.

Content Architecture (UA)

• Evaluate document length and complexity.
• Restructure content into multiple documents and organize them in a logical file tree as needed.

Publishing

Trigger Build and Publish (UA)

1. Ensure that the final documentation is pushed to the repository and the automated build is triggered.
2. Check for build errors in the Builds Dashboard.
3. Publish the documentation deliverable to the SAP Help Portal through the Deliverables Dashboard.

Stakeholder Notification (UA, SME)

• (If applicable) Consider providing a release note (for example, in a What’s New format) for the newly developed or updated feature.
• Share the published documentation link with all stakeholders.
• Add the documentation to the team’s list of owned deliverables for ongoing maintenance.

Maintenance

Change Tracking (UA, SME)

Monitor the documentation repository for issues, pull requests, and updates that may require documentation changes.

Analytics (UA, SME)

Track usage analytics and user feedback to identify areas for improvement.

Update Process (UA, SME)

Establish a process for regular review and update of documentation in response to product changes or user needs.

Best Practices for SME-UA Collaboration

Early Involvement

Involve UA professionals that leverage AI tools early in the development process to anticipate documentation needs.

Clear Communication

Use issue trackers, pull requests, and documentation comments for clear, asynchronous communication.

Shared Ownership

Foster a sense of shared ownership over documentation quality and accuracy.

Documentation as Code

Treat documentation with the same rigor as code: version control, peer review (human or AI), and continuous integration.

Continuous Improvement

Regularly review and refine documentation processes, leveraging feedback and analytics.

By following these guidelines, your team can ensure high-quality, maintainable documentation that evolves with your products—whether you have dedicated UA support, external consultants, or rely on AI-powered automation.