LDT 593 Contributing to Docker Documentation

''Welcome to Contributing to Docker Documentation'' //Empowering You to Contribute Effectively// Please enter your name for your certificate: (input-box:2bind $name,"XXXXXX=======",1,"Your Name") [[Introduction]] [[Editing Docker Documentation In Browser]] [[Editing Docker Documentation Using Markdown]] [[Submitting a Pull Request on GitHub]] [[Responding to Feedback on a Pull Request]] [[Practical Assessment]] [[Self Assessment Post-Check]] [[Download Completion Certificate]] (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' Welcome to this training on contributing to Docker’s open-source documentation. In this course, you’ll learn how to confidently submit updates to Docker documentation using GitHub. Whether it’s fixing errors, adding new information, or improving clarity, your contributions will make Docker’s documentation more accurate and helpful to your colleagues and your customers. ''Audio content: '' Narration, background music ''Description of graphics:'' TBD ''Description of interactivity and functionality: '' * Navigation to each segment is visible. * Segments show they are locked until the prerequisite segment and knowledge check have been completed. * Segments show "Continue" if a segment was started but the knowledge check has not been completed. * Segments show "Complete" with a green checkmark if they are completed entirely. * Hovering over "Complete" segments shows "Click to Review" so users can still access that content later on. * After the narration is completed, a button to repeat it will appear. * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only * ''When the course is graded, a certificate will be automatically issued. A link to download the certificate will appear on the learning module.'' ''Description of accessibility features:'' CC ]

''Introduction to Contributing to Docker Documentation'' ''Content:'' * [[Why Contributions Matter]] * [[Overview of the GitHub Repository]] * [[Reporting and Fixing Issues]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Overview:'' In this segment, introduce the importance of contributing to Docker’s open-source documentation. Highlight how keeping documentation up-to-date benefits both internal teams and customers. This segment will be short narrations paired with images to provide some background information and an opportunity for learners to rate their current skill level. ''Narration Script:'' None ''Audio content:'' Narration, background music ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only ''Description of accessibility features:'' CC ]

''Self Assessment'' Before we get started, please take a moment to evaluate your skills and comfort level with the following areas on a scale of 1 (Not Confident) to 6 (Very Confident): (dropdown: 2bind _pre_1,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Identifying documentation issues. (dropdown: 2bind _pre_2,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Editing Docker documentation using Markdown. (dropdown: 2bind _pre_3,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Running a pull request submission on GitHub. (dropdown: 2bind _pre_4,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Responding to feedback and revising your pull request. Next Segment: [[Editing Docker Documentation In Browser]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' None ''Audio content:'' None ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Radio buttons on a scale of 1 to 5 alongside each question * Button to Submit Results * Once results are submitted, display "Thank you!" followed by a button to continue to the next segment ''Description of accessibility features:'' Buttons to read the instructions and questions aloud. ]

''Editing Docker Documentation In Browser'' (text-colour:cyan)[//Embedded video//] [[Editing Docker Documentation In Browser Knowledge Check]] (link-goto: "Home", "Contributing to Docker Documentation") ''Video Script:'' //Opening video bumper// Docker makes it easy to contribute to its documentation directly from the documentation pages. In this segment, we’ll show you how to use the "Edit This Page" option to quickly make changes and submit a pull request without leaving your browser. //The screen shows the learner navigating to a Docker documentation page on docs.docker.com and clicking the "Edit This Page" button.// If you notice an error or outdated information on a Docker documentation page, click the "Edit This Page" button at the top of the right sidebar. This will take you directly to the corresponding file on GitHub. //The learner is redirected to GitHub, where a message appears saying they don’t have access to the main repository. The prompt to fork the repository appears.// You may be hesitant to make edits here, but not to worry. There are protections in place to ensure no changes are pushed before they are reviewed by the experts on the Documentation team. You don't have direct access to edit the documentation, so GitHub will automatically prompt you to fork the repository, where you can safely make and preview changes before submitting them for review. Click "Fork this repository" to create your own copy where you can make changes. //The learner clicks "Fork this repository" and is taken to the forked version of the documentation page within their GitHub account.// Now that you’ve forked the repository, you can make changes directly within GitHub’s interface. Let’s make an update to the documentation file. //The learner clicks the pencil icon to edit the documentation file and begins typing changes into the Markdown editor.// Click the pencil icon to open the Markdown editor. Here, you can edit the text directly in your browser, just like any other text editor. Be sure to follow Docker’s style guide to ensure your updates are clear, concise, and consistent. //The learner types a heading using ##, updates some content, and previews the Markdown changes by clicking the "Preview" tab.// GitHub allows you to preview your changes before submitting them. Simply click the "Preview" tab to see how your Markdown will look when published. //The learner clicks "Commit changes" and fills out a commit message, then selects "Propose changes."// Once you’re satisfied with your changes, scroll down and enter a descriptive commit message explaining what you updated. Then, click "Propose changes" to start the pull request process. //Closing video bumper// (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Overview:'' In this segment, learners will learn how to fork Docker’s documentation repository on GitHub and set up the local environment needed for making changes and running tests. ''Audio content:'' Narration, background music ''Description of interactivity and functionality: '' * Standard video controls for play, pause, etc. Prototype will use unlisted, embedded YouTube videos ''Description of accessibility features:'' CC ]

''Editing Documentation in Docker'' (text-colour:cyan)[//Embedded video//] [[Editing Docker Documentation Using Markdown Knowledge Check]] (link-goto: "Home", "Contributing to Docker Documentation") ''Video Script:'' //Opening video bumper// Now that you’ve forked the repository and are working in GitHub, it’s time to make updates to the Docker documentation. In this segment, we’ll walk through how to edit the documentation using Markdown directly in the browser. //The learner clicks the pencil icon in GitHub to edit the documentation page.// In GitHub, click the pencil icon to start editing the file directly in the browser. The editor uses Markdown, a simple markup language that allows you to format text with headings, lists, links, and more. //The Markdown editor opens, and the learner highlights existing content in the document.// In this editor, you’ll see the existing content in Markdown format. Let’s go over some of the basic Markdown elements you’ll use while editing Docker’s documentation. //The learner adds a level-2 heading with (bg:#343a40)+(font:"Courier")[##], creates a bulleted list with (bg:#343a40)+(font:"Courier")[- List Item], and adds a link with (bg:#343a40)+(font:"Courier")[`[Docker Documentation]`(https://docs.docker.com). ]// To create a heading, simply type a (bg:#343a40)+(font:"Courier")[#] symbol followed by the heading text. The number of (bg:#343a40)+(font:"Courier")[#] symbols define the level of the heading. For lists, use a dash followed by a space and the list item. To add a link, use square brackets for the link text and parentheses for the URL. //The learner makes a few more changes, including fixing a typo and updating an outdated link.// You can now make your edits. For example, fix any typos, update outdated links, or improve clarity. Be sure to follow Docker’s documentation style guide to ensure that your changes are consistent and professional. //The learner clicks the "Preview" tab to see how the Markdown will be rendered.// Once you’ve made your changes, click the "Preview" tab to see how they’ll be rendered on the site. This preview helps you check your formatting for headings, lists, and links. //The learner switches back to the "Edit" tab to make a final change, then scrolls down to the commit message section.// When you’re satisfied with your changes, scroll down to the commit message section. Enter a brief but descriptive message explaining what you changed, like "Fixed typo in introduction" or "Updated outdated link to documentation." //The learner enters a commit message and clicks "Propose changes."// Once your commit message is ready, click "Propose changes." This saves your changes and moves you to the pull request phase, where you’ll submit your updates for review. //Closing video bumper// (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Overview:'' In this segment, learners will learn how to edit Docker’s documentation using Markdown, with a focus on adhering to Docker’s style guidelines and ensuring the changes are clear, concise, and accurate. ''Audio content:'' Narration, background music ''Description of interactivity and functionality: '' * Standard video controls for play, pause, etc. Prototype will use unlisted, embedded YouTube videos ''Description of accessibility features:'' CC ]

''Submitting a Pull Request on GitHub'' (text-colour:cyan)[//Embedded video//] [[Submitting a Pull Request on GitHub Knowledge Check]] (link-goto: "Home", "Contributing to Docker Documentation") ''Video Script:'' //Opening video bumper// Now that you’ve made your changes and previewed them, it’s time to submit your pull request. A pull request lets your colleagues in the Documentation team review your changes before they are merged into the official Docker documentation, where they can be viewed by your customers and team members. //The learner clicks "Propose changes" after entering a commit message in GitHub.// You’ve already entered a descriptive commit message and proposed your changes. GitHub will now redirect you to the pull request page. //The learner clicks "Create pull request" and is taken to the pull request form, where they fill in the title and description.// On the pull request page, you’ll need to provide a title and description of your changes. The title should be clear and concise, such as "Fixed typo in installation guide" or "Updated link to Docker documentation." In the description, explain the changes in more detail and reference any related issues or feedback you’ve addressed. //The learner types a detailed description in the pull request form, explaining the changes and linking to the related issue.// If your changes are related to a specific issue or feedback, be sure to mention that in the description. This helps reviewers understand why the changes were made and how they address a particular problem. //The learner reviews the pull request and clicks "Create pull request."// Once you’ve filled in the title and description, review the pull request one last time to make sure everything is correct. When you’re ready, click "Create pull request." //The learner’s pull request is submitted and shown in the GitHub interface.// Your pull request has now been submitted. Reviewers will be able to look over your changes and leave comments or requests for adjustments if needed. Once approved, your changes will be merged into the official Docker documentation. //Closing video bumper// (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Overview:'' Learners will be guided through the process of submitting a pull request (PR) to propose changes to Docker’s documentation. ''Audio content:'' Narration, background music ''Description of interactivity and functionality: '' * Standard video controls for play, pause, etc. Prototype will use unlisted, embedded YouTube videos ''Description of accessibility features:'' CC ]

''Responding to Feedback on a Pull Request'' (text-colour:cyan)[//Embedded video//] [[Responding to Feedback on a Pull Request Knowledge Check]] (link-goto: "Home", "Contributing to Docker Documentation") ''Video Script:'' //Opening video bumper// Once you’ve submitted your pull request, it will be reviewed by other contributors or maintainers: in this case, your colleagues in the Docker documentation team. In this segment, we’ll guide you through how to handle feedback and make updates to your pull request. //The screen shows a pull request with reviewer comments requesting changes, including a comment tied to a specific line of code.// When a reviewer requests changes, you’ll see comments directly in your pull request. Reviewers can leave general feedback or comment on specific lines in the document, making it easy for you to see what needs to be updated. //The learner clicks on a comment and is taken to the relevant line in the document.// To view the comment in context, simply click on it. GitHub will show you the exact line or section where the reviewer has requested a change. //The learner clicks the pencil icon next to the file in the pull request to edit the file directly in GitHub.// To make the requested changes, you don’t need to switch to a local environment. Simply click the pencil icon next to the file you want to edit, and GitHub will open the document in its in-browser editor. //The learner edits the file in the GitHub editor, updates the content based on the reviewer's feedback, and saves the changes.// Make the necessary changes directly in the GitHub editor, just like you did before. Once your changes are complete, scroll down to commit the changes. //The learner enters a new commit message (e.g., "Addressed reviewer feedback") and commits the changes.// In the commit message, describe what changes you made to address the feedback. For example, "Addressed reviewer feedback on typo corrections." Then, click "Commit changes." This updates the pull request with your new edits. //The updated pull request shows the new commits and marks the reviewer’s comment as resolved.// After committing your changes, your pull request will be updated, and the reviewer’s comments will be marked as resolved. If all feedback has been addressed, your pull request is ready for final review. //Closing video bumper// (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Overview:'' This segment will teach learners how to handle feedback from reviewers and revise their pull request if needed. ''Audio content:'' Narration, background music ''Description of interactivity and functionality: '' * Standard video controls for play, pause, etc. Prototype will use unlisted, embedded YouTube videos ''Description of accessibility features:'' CC ]

''Practical Exercise – Submitting a Pull Request'' (link-goto: "Home", "Contributing to Docker Documentation") Now that you’ve completed the training modules, it’s time to apply what you’ve learned in a real-world scenario. Follow these steps to complete your practical exercise by making a change to Docker’s documentation and submitting a pull request for review. 1. ''Navigate to the Documentation Page:'' * Go to the Docker documentation page at [Placeholder URL]. * Review the page and identify the requested changes that need to be made. 2. ''Edit the Documentation:'' * Click the "Edit This Page" button at the bottom of the page. This will take you to GitHub, where you can make the necessary changes to the documentation. * Once in GitHub, click the pencil icon to edit the Markdown file directly in your browser. * Make the requested changes, ensuring you follow Docker’s style guide. 3. ''Preview Your Changes:'' * After making your changes, click the "Preview" tab to ensure the Markdown formatting looks correct. * Verify that all changes are accurately reflected and follow best practices for documentation updates. 4. ''Submit a Pull Request:'' * Once you’re satisfied with your changes, scroll down to the commit section. * Enter a descriptive commit message explaining what you updated, such as "Updated documentation based on requested changes." * Click "Propose changes" to move to the pull request page. * Provide a title and description for your pull request, then click "Create pull request." 5. ''Respond to Reviewer Feedback:'' * After submitting your pull request, reviewers may request changes. If this happens, you’ll need to follow the feedback process outlined in the earlier segment. * Update the documentation as needed, commit the changes, and update the pull request. [[Self Assessment Post-Check]] (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Description of knowledge check: '' * Step-by-step instructions on how to submit a pull request. * SME will provide the specific repository URL and a change they want made. This can be provided on an individual basis or may be embedded into the lesson. This will be confirmed prior to the delivery of the prototype. * Since this will need to be graded by the instructor, the prototype use a free text field for learners to to enter a link to their pull request. ''Completion Criteria:'' * Learners must successfully submit a pull request that follows all of Docker’s documentation and GitHub best practices. * If revisions are required by the reviewers, the learner must update their pull request and resubmit it for approval. * The exercise is considered complete when the pull request approved by the reviewer. ''Description of interactivity and functionality: '' * When the course is graded, a certificate will be automatically issued. A link to download the certificate will appear on the learning module. ''Description of accessibility features:'' Buttons with each step to read the step aloud. ]

''Self Assessment'' Now that you've completed this training program, please take a moment to evaluate your skills and comfort level with the following areas on a scale of 1 (Not Confident) to 6 (Very Confident): (dropdown: 2bind _post_1,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Identifying documentation issues. (dropdown: 2bind _post_2,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Editing Docker documentation using Markdown. (dropdown: 2bind _post_3,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Running a pull request submission on GitHub. (dropdown: 2bind _post_4,"1 - Not At All Confident","2 - Slightly Confident","3 - Moderately Confident","4 - Confident","5 - Very Confident") Responding to feedback and revising your pull request. (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' None ''Audio content:'' None ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Radio buttons on a scale of 1 to 5 alongside each question * Button to Submit Results * Once results are submitted, display "Thank you!" followed by a button to return to the home page. ''Description of accessibility features:'' Buttons to read the instructions and questions aloud. ]

''Knowledge Check:'' ''What happens when you click the "Edit This Page" button on Docker’s documentation site?'' A. You can make direct changes to the main Docker repository. B. You are redirected to a preview site. C. You are taken to the documentation style guide. (text-colour:green)[''D. You are prompted to fork the repository before making changes.''] Back to [[Editing Docker Documentation In Browser]] Go to [[Editing Docker Documentation Using Markdown]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Description of knowledge check: '' * Question 1: Multiple-choice question with one correct answer ''Description of accessibility features:'' Button read the question and answers aloud. ]

''Knowledge Check:'' ''Enter the Markdown syntax needed to recreate the following formatting examples:'' --- ##Heading 2 Answer (bg:#343a40)+(font:"Courier")[ `##Heading 2`] --- * Bulleted List Answer (bg:#343a40)+(font:"Courier")[`- Bulleted List`] OR (bg:#343a40)+(font:"Courier")[`* Bulleted List`] --- (link:"Docker")[(goto-url: 'https://docker.com/')] Answer (bg:#343a40)+(font:"Courier")[ `[Docker]`(https://docker.com) ] --- Back to [[Editing Docker Documentation Using Markdown]] Go to [[Submitting a Pull Request on GitHub]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Description of knowledge check: '' * Questions 1-3: Fill-in-the-blank questions where the learner must type the syntax required to recreate the formatting. Answer fields are case sensitive. ''Description of accessibility features:'' Button to read the directions aloud. ]

''Knowledge Check:'' You’ve just made changes to a file in Docker’s documentation. Which of the following is the correct process to submit those changes? A. Push changes directly to the main branch. (text-colour:green)[''B. Commit changes and open a pull request, providing a title and description of your changes.''] C. Edit the file again before committing. D. Email the maintainer to inform them of the changes. Back to [[Submitting a Pull Request on GitHub]] Go to [[Responding to Feedback on a Pull Request]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Description of knowledge check: '' * Question 1: Multiple choice question with one correct answer ''Description of accessibility features:'' Button to read the question and answers aloud. ]

''Knowledge Check:'' If a reviewer requests changes to your pull request, which steps should you follow to address the feedback? A. Create a new pull request with the updated changes. B. Close the pull request and start over. (text-colour:green)[''C. Edit the file directly in GitHub, commit the changes, and update the pull request.''] D. Switch to a local environment to make changes. Back to [[Responding to Feedback on a Pull Request]] Go to [[Practical Assessment]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Description of knowledge check: '' * Question 1: Multiple choice question with one correct answer ''Description of accessibility features:'' Button to read the question and answers aloud. ]

## Certificate of Completion This certificate is proudly presented to: (if: $name is "Your Name")[Learner Name Not Entered](else-if: $name is 0)[Learner Name Not Entered](else:)[$name] For successfully completing the course: ### Contributing to Docker Documentation This course provided comprehensive training on how to identify documentation issues, make updates using GitHub, and submit changes via pull requests. The learner demonstrated proficiency in: * Identify and fix issues in Docker’s documentation. * Submit updates using GitHub’s pull request process. * Follow best practices for maintaining clear and accurate documentation. * Confidently contribute to Docker’s open-source documentation. Date of Completion: (current-date:) (link-goto: "Home", "Contributing to Docker Documentation")

''Why Contributions Matter'' //Visual: Docker documentation page with a highlighted error, such as outdated information// Next: [[Overview of the GitHub Repository]] Back: [[Introduction]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' Docker’s documentation is a vital resource for customers and internal teams alike. It provides critical information for troubleshooting, installing, and using Docker’s products. However, software evolves quickly, and sometimes the documentation doesn’t keep up. When that happens, support engineers like you are often the first to spot issues. By contributing updates to the documentation, you help reduce the number of repetitive support cases and empower users to solve problems on their own. Your contributions ensure that Docker’s documentation stays accurate and useful. ''Audio content:'' Narration, background music ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only ''Description of accessibility features:'' CC ]

''Overview of the GitHub Repository'' //Visual: Screenshot of Docker’s GitHub repository homepage// Next: [[Reporting and Fixing Issues]] Back: [[Why Contributions Matter]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' All of Docker’s documentation is hosted on GitHub, a platform for version control and collaboration. You’ll be working within Docker’s open-source documentation repository, where you’ll be able to make changes by following the GitHub process of forking, editing, and submitting pull requests. ''Audio content:'' Narration, background music ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only ''Description of accessibility features:'' CC ]

''Reporting and Fixing Issues'' //Visual: Screenshot of the "Request Changes" link in the Docker docs side-by-side with the GitHub page that opens from that link, a form to open an issue for that specific page// Next: [[What You'll Learn]] Back: [[Overview of the GitHub Repository]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' When you spot an issue in the documentation, you have the option to report it via the link in the top of the right sidebar, or you can contribute by fixing it yourself. Your fixes can include refreshing outdated information, adding clarifications, or correcting errors. ''Audio content:'' Narration, background music ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only ''Description of accessibility features:'' CC ]

''What You'll Learn'' //Visual: Overview of the course objectives, laid out visually// Next: [[Self Assessment Pre-Check]] Back: [[Reporting and Fixing Issues]] (link-goto: "Home", "Contributing to Docker Documentation") (b4r:"solid","none")+(b4r-colour:grey,white)[ ''Slide Notes'' ''Narration Script:'' Throughout this course, you’ll learn how to: * Identify and fix issues in Docker’s documentation. * Submit updates using GitHub’s pull request process. * Follow best practices for maintaining clear and accurate documentation. * Confidently contribute to Docker’s open-source documentation. Let’s start by evaluating your current comfort level with these processes. ''Audio content:'' Narration, background music ''Description of graphics: '' TBD ''Description of interactivity and functionality: '' * Button to repeat the narration * Button to change between three modes: Audio Only, Audio and Transcript, Transcript Only ''Description of accessibility features:'' CC ]