Tutorial 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

• You have a basic understanding of tutorials. Read The Big Picture on Tutorials.

• You have installed the required software. Follow instructions in Configure your machine for Tutorial Authoring.

• You have ensured project staffing. Within the scope of your tutorial 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

See Plan Tutorials in the SAP Tutorial Navigator page in Workzone. The development team (that SME is part of) plays a key role in defining the roadmap and priorities for tutorials.

Scenario Selection (SME)

• Identify high-priority scenarios for tutorials based on user needs, product features, and roadmap goals.
• Ensure scenarios align with the team and area strategy, focusing on the most common and impactful use cases.
• Ensure technical feasibility and accuracy of the scenarios early in the planning phase.
• Define prerequisites, dependencies, and potential challenges users might face.

Infrastructure Setup

Request Repository Creation (UA, SME)

1. Submit a request for the creation of individual Tutorial Navigator repositories (both QA and PROD environments). For more details, see Get Access in the SAP Tutorial Navigator page in Workzone.

2. Ensure that the repositories are part of the correct GitHub organization SAP Tutorials and content from each repository is built to the corresponding Tutorial Navigator environment. You should have the following repositories:

   • A repository with name <your-repo-name> that is connected to the Tutorial Navigator PROD environment.
   • Another repository with name <your-repo-name>-Contribution that is connected to the Tutorial Navigator QA environment.

Repository Administration (UA, SME)

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

  • Maintain the repo’s README and compatibility with company requirements (e.g., REUSE tool).
  • 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.

Define Collaboration Workflow (UA, SME)

• Define clear contribution guidelines for SME and UA to follow when committing to the repository.
• Establish a shared understanding of the tutorial creation process within the development team. For example, who will prioritize topics, who will define tutorial roadmap, who will create the raw draft of the tutorial, who will take care of technical review, who will proofread, edit, approve, publish, etc.
• Use a collaboration tool (e.g., GitHub issues, project boards, or a shared document) to track tutorial progress, feedback, and updates.

Troubleshooting

Link to troubleshooting info goes in this section

Changes not building

• There can be multiple reasons. Should check md syntax, metadata, tags, repo setup, etc.

Create Drafts

Raw Drafts (SME)

• SME is responsible for creating initial tutorial drafts in the repository with name <your-repo-name>-Contribution that is connected to the Tutorial Navigator QA environment.

• Drafts must adhere to the following requirements:

  • Follow the Tutorial Style Guide and 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.
  • Include any known prerequisites, expected outcomes, and potential pitfalls.
  • Have front matter metadata to ensure the tutorial is built and displayed correctly in the Tutorial Navigator QA environment.

Testing

End-to-End Testing (UA, SME)

• Test the tutorial scenario end-to-end, following the 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.

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

• Identify any issues, discrepancies, or deviations and document them.

Iterative Improvement (UA, SME)

• Clarify issues and refine the tutorial.
• Add missing prerequisites, steps, explanations, context, code snippets, screenshots, and notes as needed.
• Repeat testing and refinement until the tutorial can be completed successfully without SME assistance. (UA)

Review

Language and Style Editing (SME)

• Ensure the content complies with the SAP Tutorial Navigator Style Guide and the SAP Style Guide for Technical Communication in terms of formatting, terminology, and tone.

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).

Technical Review (SME)

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

Copy-Editing

Quality Review (UA)

• Perform a deep edit of the tutorial for language, clarity, and style.
• Compare the tutorial against the Review Checklist for Tutorials.
• If applicable, submit the tutorial for a formal quality review cycle (QRC).
  • Alternatively, use AI to simulate peer review, providing feedback on clarity, completeness, and structure.
• Address any feedback received during the QRC process.

Complexity Evaluation (UA)

• Assess the tutorial length and complexity.
• If necessary, split the tutorial into smaller, logically grouped tutorials with a clear execution sequence.

Publishing

Move to Production (UA, SME)

1. Copy the tutorial from the repository with name <your-repo-name>-Contribution that is connected to the Tutorial Navigator QA environment to the repository with name <your-repo-name> that is connected to the Tutorial Navigator PROD environment - local action between two locally cloned repos.
2. Commit the changes to the repository with name <your-repo-name> that is connected to the Tutorial Navigator PROD environment to trigger the build and publication process.

Consider Groups and/or Missions (UA, SME)

• Bringing together tutorials in groups and/or missions defines a logical sequence of executing tutorials that represent different steps of a bigger scenario.
• For details on what’s the relation between tutorials, groups, and missions in the SAP Tutorial Navigator, see How to put together a mission and Create a Tutorial Mission or Group.

Share with Stakeholders (UA, SME)

• (If applicable) Consider providing a release note (for example, in a What’s New format) for the newly developed tutorial.
• Share the productive link to the tutorial with all stakeholders, including developers, the entire team, and other relevant stakeholders.

Maintenance

Tutorials require regular updates to stay relevant and accurate.

Scheduled Reviews (UA, SME)

• Add the tutorial to the list of owned and maintained tutorials.
• Perform periodic reviews of the tutorial to ensure it reflects the latest product updates and best practices.
• Test the tutorial end-to-end at regular intervals to identify and address any issues.

Feedback Loop (UA, SME)

• Monitor feedback from users, developers, and stakeholders.

Analytics (UA, SME)

• Use analytics from the Beta Tutorial Dashboard to identify areas for improvement. If you don’t have access to the dashboard, follow the instructions to get access to the Beta Tutorial Dashboard.

Issue Tracking (UA, SME)

• Regularly check the official repository for issues related to the tutorial.
• Address reported issues promptly and update the tutorial as needed.

Best Practices for Collaboration

Early and Frequent Communication

Maintain open communication between SME and UA throughout the process to ensure alignment and resolve issues quickly.

Document Decisions

Keep a record of decisions made during the tutorial creation process, including feedback from reviews and changes made.

Focus on the User

Always prioritize the end-user experience by ensuring tutorials are clear, concise, and actionable.

Iterate and Improve

Treat tutorials as living documents that evolve with user needs and product changes.

By following these guidelines, UA and SME can collaborate effectively to create high-quality tutorials that empower users and enhance their experience with the product.