diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json deleted file mode 100644 index e8481db..0000000 --- a/.devcontainer/devcontainer.json +++ /dev/null @@ -1,27 +0,0 @@ -// For format details, see https://aka.ms/vscode-remote/devcontainer.json or the definition README at -// https://github.com/microsoft/vscode-dev-containers/tree/master/containers/debian-9-git -{ - "name": "Marp", - "service": "container-doc", - // Use 'settings' to set *default* container specific settings.json values on container create. - // You can edit these settings after create using File > Preferences > Settings > Remote. - "settings": { - "terminal.integrated.shell.linux": "/bin/bash", - "markdown.marp.enableHtml": true, - "markdown.marp.themes": [ - "slide/theme.css" - ], - "cSpell.language": ",en" - }, - // Use 'appPort' to create a container with published ports. If the port isn't working, be sure - // your server accepts connections from all interfaces (0.0.0.0 or '*'), not just localhost. - // "appPort": [], - // Add the IDs of extensions you want installed when the container is created in the array below. - "extensions": [ - "marp-team.marp-vscode", - "hediet.vscode-drawio", - "jebbs.plantuml", - "yzhang.markdown-all-in-one", - "streetsidesoftware.code-spell-checker" - ] -} diff --git a/.github/linters/.markdown-lint.json b/.github/linters/.markdown-lint.json deleted file mode 100644 index eb17e0d..0000000 --- a/.github/linters/.markdown-lint.json +++ /dev/null @@ -1,11 +0,0 @@ - -{ -"frontMatter": false, -"MD004": false, -"MD013": false, -"MD022": false, -"MD026": false, -"MD031": false, -"MD033": false, -"MD041": false -} \ No newline at end of file diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt deleted file mode 100644 index 911eec2..0000000 --- a/.github/styles/vocab.txt +++ /dev/null @@ -1,14 +0,0 @@ -Analytics -AWS -bg -Codespaces -cron -DRY -GIT -GitHub -github -IntelliJ -markdownlint -Marp -Netlify -VSCode \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index 3feb649..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,111 +0,0 @@ -# The name of the workflow as it will appear in the Actions tab -# of the GitHub repository. -name: build-web-site - -# Run this workflow every time a new commit pushed to your repository -on: push - -jobs: - lint: - name: Markdown Lint - # Set the agent to run on - runs-on: ubuntu-latest - ################## - # Load all steps # - ################## - steps: - ########################## - # Checkout the code base # - ########################## - - name: Checkout Code - uses: actions/checkout@v2 - with: - # Full git history is needed to get a proper list of changed files within `super-linter` - fetch-depth: 0 - - ################################ - # Run Linter against code base # - ################################ - - name: Lint Code Base - #uses: github/super-linter@v3.13.1 - # Workaround for https://github.com/github/super-linter/issues/938 - uses: docker://github/super-linter:v3.13.1 - env: - VALIDATE_ALL_CODEBASE: true - VALIDATE_MARKDOWN: true - DEFAULT_BRANCH: main - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - MARKDOWN_CONFIG_FILE: .markdown-lint.json - - linkcheck: - name: Links - runs-on: ubuntu-latest - if: github.ref == 'refs/heads/main' - steps: - - uses: actions/checkout@master - # https://github.com/marketplace/actions/markdown-link-check - - uses: gaurav-nelson/github-action-markdown-link-check@v1 - - spellCheck: - name: Spelling - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@master - - uses: rojopolis/spellcheck-github-actions@0.5.0 - name: Spellcheck - - StyleCheck: - name: Style and Voice - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@master - - name: Style check - uses: errata-ai/vale-action@v1.3.0 - with: - styles: | - https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip - https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip - env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} - - # Set the job key. The key is displayed as the job name - # when a job name is not provided - build-deploy: - #Name of the job - name: Build github pages - - #Set the type of machine to run on - runs-on: ubuntu-latest - if: github.ref == 'refs/heads/main' - needs: - - lint - - spellCheck - - linkcheck - env: - MARP_VERSION: 0.21.1 - steps: - # Checks out a copy of your repository on the ubuntu-latest machine - # https://github.com/actions/checkout - - name: Checkout code - uses: actions/checkout@v2 - with: - clean: true - token: ${{ github.token }} - - # Runs the website build - - run: sudo wget -qO- https://github.com/marp-team/marp-cli/releases/download/v0.21.1/marp-cli-v$MARP_VERSION-linux.tar.gz | tar xvz - - run: chmod +x marp && export PATH=$PATH:$(pwd) && mkdir site && marp slides/README.md --html -o site/index.html - # https://github.com/actions/upload-artifact - - uses: actions/upload-artifact@v2 - with: - name: slides - path: site/index.html - - #https://github.com/marketplace/actions/deploy-to-github-pages - - name: Deploy to GitHub Pages - uses: JamesIves/github-pages-deploy-action@3.6.2 - with: # Set the secret as an input - GITHUB_TOKEN: ${{ secrets.DEPLOYMENT_ACCESS_KEY }} - BRANCH: gh_pages - FOLDER: site \ No newline at end of file diff --git a/.gitignore b/.gitignore deleted file mode 100644 index b5acb8c..0000000 --- a/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -.github/styles/Microsoft/* -.github/styles/write-good/* diff --git a/.ignoredWords.txt b/.ignoredWords.txt deleted file mode 100644 index dc6900e..0000000 --- a/.ignoredWords.txt +++ /dev/null @@ -1,53 +0,0 @@ -angegar -analytics -backgroundImage -bg -Bitbucket -cd -ci -cli -CLI -Codespaces -cron -dev -DevOps -Draw.io -dxc -DXC -gif -gil -github -GitLab -GitPod -gource -https -Hugo -inslide -IntelliJ -io -jacques -Jekyll -Jenkinsfile -jpeg -jpg -laurent -linter -linters -Linter -markdownlint -marp -Marp -matomo -mkdocs -MkDocs -Netlify -ojacques -olivier -PlantUML -PNG -PPTX -px -shortcodes -url -vscode -VSCode \ No newline at end of file diff --git a/.spellcheck.yml b/.spellcheck.yml deleted file mode 100644 index afb60b7..0000000 --- a/.spellcheck.yml +++ /dev/null @@ -1,18 +0,0 @@ -matrix: -- name: Markdown - aspell: - lang: en - dictionary: - encoding: utf-8 - wordlists: - - .ignoredWords.txt - pipeline: - - pyspelling.filters.markdown: - - pyspelling.filters.html: - comments: false - ignores: - - code - - pre - sources: - - '**/*.md' - default_encoding: utf-8 \ No newline at end of file diff --git a/.vale.ini b/.vale.ini deleted file mode 100644 index 26141cd..0000000 --- a/.vale.ini +++ /dev/null @@ -1,10 +0,0 @@ -StylesPath = .github/styles -MinAlertLevel = suggestion - -[*.md] -BasedOnStyles = Microsoft, write-good - -Microsoft.We = NO -Microsoft.HeadingAcronyms = NO -Microsoft.Headings = NO -Microsoft.Acronyms = NO diff --git a/LICENSE b/LICENSE deleted file mode 100644 index c43bec7..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2020 Laurent Gil - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md deleted file mode 100644 index 83f33c8..0000000 --- a/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# CI and CD for Documentation - -[![build-web-site](https://github.com/documentation-as-code/addo-daac/workflows/build-web-site/badge.svg)](https://github.com/documentation-as-code/ci-cd-for-documentation/actions?query=workflow%3Abuild-web-site+branch%3Amain) - -## Purpose - -This is the demo repository for All Day DevOps 2020 session on "CI and CD for documentation." - -## Brainstorm - -Brainstorm on what will be the content of the presentation: - -[![Brainstorm](brainstorm.drawio.png)](https://app.diagrams.net/?sync=none#Hdocumentation-as-code%2Fci-cd-for-documentation%2Fmain%2Fbrainstorm.drawio.png) - -## Slides - -[https://documentation-as-code.github.io/ci-cd-for-documentation/](https://documentation-as-code.github.io/ci-cd-for-documentation/) - -See also [Marp documentation](https://marpit.marp.app/). diff --git a/brainstorm.drawio.png b/brainstorm.drawio.png deleted file mode 100644 index f357766..0000000 Binary files a/brainstorm.drawio.png and /dev/null differ diff --git a/index.html b/index.html new file mode 100644 index 0000000..ccb9275 --- /dev/null +++ b/index.html @@ -0,0 +1,786 @@ +

+
+
+
+

CI and CD

+

For documentation

+ +
+
+
+
+

The quest for great documentation

+

🏰🦄🤴👸🐴👻⚔🗡🏴‍☠️

+ +
+
+

We do a lot of documentation

+

(as code)

+
    +
  • 1 service catalog: the entry point
    • +
  • 174 services: technical documentation
    • +
  • 630 contributors
    • +
+ +
+
+

Service catalog

+

With Hugo

+ +
+
+

Service documentation

+

With MkDocs +
+material theme

+ +
+
+
+
+

🤯

+

DXC, Microsoft, GitHub, GitLab, AWS all use "Documentation as code"

+

Because:

+
    +
  • It's fast, secure and cheap (static sites)
    • +
  • It's easier to contribute to / keep up-to-date
    • +
  • It's battle tested
    • +
  • It's engineered
    • +
  • We can monitor it (think analytics)
    • +
+ +
+
+

Our challenges

+
    +
  • Common look & feel
    • +
  • Common voice
    • +
  • DRY: Don't Repeat Yourself
    • +
  • Diagrams: what changes?
    • +
  • Broken links
    • +
  • Publishing
    • +
+ +
+
+
+
+

CI and CD for documentation

+

CI

+
    +
  • Spell checking
    • +
  • Check for approved acronyms / custom dictionary
    • +
  • One voice
    • +
  • Periodically check for 404 links
    • +
+

CD

+
    +
  • Automate publishing
    • +
+ +
+
+


+

+

+

In practice

+ +
+
+

Authoring

+

Leverage Markdown

+

Use your favorite code editor:

+ + +
+
+

Authoring (1)

+

Add editor extensions

+ + +
+
+

Authoring (2)

+

GitHub Codespaces or GitPod

+
    +
  • Edit directly from the browser
    • +
  • Make it easy for tech writers:
    +no git clone/branch/push
    +git reset origin/main --hard
    • +
  • Shared extensions across development environments
    • +
+ +
+
+

Authoring (3)

+

Pick a tool

+ + +
+
+

Orchestrating

+
    +
  • GitHub Actions
    • +
  • GitLab CI
    • +
  • Jenkins (Jenkinsfile) 👈
    • +
  • AWS code pipeline
    • +
  • Azure DevOps
    • +
+ +
+
+

CI: Linter

+

CLI linter

+ +

Editor linter

+ + +
+
+

CI: Spell Checker

+

CLI spell checker

+ + +

Editor spell checker

+ + +
+
+

CI: Link checker

+ +

404 links

+

markdown-link-check

+ +
+
+

CI: Testing (4)

+

Style / voice

+

Vale

+ +
+
+

Publishing (CD)

+ +

GIT Hosting

+

GitHub, GitLab, Bitbucket

+

Web hosting

+ + +
+
+

Quick starts

+

Making it easy with:

+ + +
+
+

Thank you 🙏

+ +
+

speaker: Olivier + +Thank you. Today, Laurent and I are going to talk about "Documentation as Code" and more specifically CI and CD for documentation. + +But first, let us introduce ourselves: + +Speakers: Olivier & Laurent +- Short intro + +(NOTE: embed Olivier & Laurent's faces / OBS) + +Laurent: +Hello I am Laurent, I also work for DXC Technology where I am acting internally as a DevOps Coach and externally as a CI and CD expert. I hope we will manage to show you the benefits of the CI and CD practices for documentation as code, as well as how easy it is to do it.

speaker: Olivier + +Laurent and I both work for DXC technology customers. DXC technology is a global IT services leader. + +With 19.6B$ of revenues, 6000 customers and 138000 employees across 70 countries, we are - in many dimensions - big.

Back to this presentation. + +This presentation is an experience report, because we have learned so much from others through this format. + +This presentation is about our quest: the quest for great documentation. + +Previously, +- our documentation was the last thing we would do, +- it had spelling and syntax mistakes, +- we were using the passive voice, but sometimes the active voice +- it was often inaccurate, +- a few were able to fix it and we had to contact them through email, +- several authors could not work on the same piece of documentation without going through lengthy merges, +- and links would break very often without us even knowing. + +Today, it's a very different situation +- we have one service catalog and 174 services documented +- documentation readers can contribute to the documentation using a Pull Request +- we can report bugs and fix them +- documentation changes go through a series of tests and gates +- it's bigger yet more thorough and precise than ever +- It has the same look & feel +- it's written in the same style

The context for the experience report is our own company (but we do that with our customers too): +- A platform which provides intelligence, orchestration, and automation capabilities to our managed service offerings +- 630 contributors (developers, testers, scrum masters) +- 1 "service catalog" site +- 174 services documented

Speaker: Olivier + +We have 2 types of documentation: +- Service catalog +- Service documentation + +Service catalog: +- Marketing / catalog site: mix of text, benefits, highlights, videos

Speaker: Olivier + +The documentation for each service leverages Mkdocs which we love because it's very close to markdown and does not require a separate git repository.

Speaker: Olivier

Fast, secure and cheap (static sites) + - Comparing to WordPress/Drupal/Confluence type solutions + - More secure (no DB to hack) + - Portable (even offline) +Easier to contribute to / keep up-to-date + - The pull request / merge request workflow fully applies +Battle test documentation +Monitoring: + - "Is this page useful?" + - Analytics: like Google Analytics or Open Source alternative: Matomo + - Reader journey, what is useful

speaker: Olivier

speaker: Olivier + +This video is a visualization of our service catalog repository documentation, as it evolves. + +In summary, we needed to build great documentation, at scale, battle tested and ensure it would not break over time. + +Looks like code to us!

Speaker: Olivier

Speaker: Laurent + +Hi, during the second part of the talk, I will give you a brief overview of the state of the art about CI/CD tools for documentation as code. + +Let's start with the development environment, which environment is required ?

Speaker: Laurent + +To write the documentation we use the Markdown language. Yes, I said language. Indeed, you write your documentation in your native language then you surround it with decorators which will modify the format. + +There is no need to have developer skills, the Markdown syntax is easy to use.

Speaker: Laurent + +Most of the integrated development environments (IDE) can be enhanced with multiple plugins. Here is a short list of what we used to use.

Speaker: Laurent + +GitHub offers an online VSCode instance attached to your GitHub repository. The Codespaces feature allows all the developer to share the same set of extensions as this configuration is automatically shared across the development environment attached to the project.

- Jekyll : Based on Ruby, it's hard to configure for a non developer users especially under windows => hard to contribute +- Hugo: + - HTML + go template for documentation + - Far from standard markdown => hard for non dev users + - shortcodes: like macro, for documentation. Ensures uniformity + - Recommended if you need to have multiple page template in your web site + +- Marp: + - Excellent to generate slide deck + - Follow Markdown syntax + - Presenter view + - Template with CSS + - Extensible + - Output PPTX, PDF, PNG, JPEG +- MkDocs: + - Follow Markdown syntax + - Closest to plain markdown, great for tech docs + - Can integrate native HTML web page => Can integrate Marp outputs

Speaker: Laurent + +Use your favorite orchestration tool to deploy your documentation. +Those tools now offer predefined features to ease your pipeline; + +We will see a set of GitHub Market Actions used in this documentation pipeline.

We use linters to check code "doc" quality. + +2 types of linters +- CLI: to be integrated in the pipeline +- Editor: check syntax as you type, before commit and push

Identically, we can find CLI spell checker and Editor one + +Work with direction of exception and custom dictionary

Links must be checked regularly (cron) as they break without you doing any change.

Used to ensure your a vocabulary style guide.

You don't have to spin up a virtual machine or server to host your documentation site. Major Source Code Management applications already host web pages.

Speaker: Laurent + +We have been using GitHub template to ease the creation of Documentation As Code

\ No newline at end of file diff --git a/slides/README.md b/slides/README.md deleted file mode 100644 index 6881cf7..0000000 --- a/slides/README.md +++ /dev/null @@ -1,453 +0,0 @@ ---- -marp: true -theme: default -style: | - footer { - position: absolute; - #left: 50%; - bottom: 7px; - } - section header a { color: white;} - video.inslide { - position: absolute; - width: 70%; - height: 70%; - } -paginate: false -footer: '[github/ojacques](https://github.com/ojacques)             [github/angegar](https://github.com/angegar)' ---- - -
-
-
-
- -# CI and CD -## For documentation - - - ---- - - - - ---- - - -The quest for great documentation - -# 🏰🦄🤴👸🐴👻⚔🗡🏴‍☠️ - - - ---- - -# We do a lot of documentation - -## (as code) - -- 1 service catalog: the entry point -- 174 services: technical documentation -- 630 contributors - - - ---- - -![bg 95% right:62%](https://github.com/documentation-as-code/ci-cd-for-documentation/raw/main/slides/service-catalog-hugo.gif) - -# Service catalog -With [Hugo](https://gohugo.io/) - - ---- - -![bg 95% right:62%](https://github.com/documentation-as-code/ci-cd-for-documentation/raw/main/slides/service-documentation-mkdocs.gif) - -# Service documentation -With [MkDocs](https://www.mkdocs.org/) + -[material theme](https://squidfunk.github.io/mkdocs-material/) - - - ---- - -![bg center 60%](https://github.com/documentation-as-code/ci-cd-for-documentation/raw/main/slides/doc-site.jpg) - - ---- -# 🤯 - -## DXC, Microsoft, GitHub, GitLab, AWS all use "Documentation as code" - -Because: - -- It's fast, secure and cheap (static sites) -- It's easier to contribute to / keep up-to-date -- It's battle tested -- It's engineered -- We can monitor it (think analytics) - - - ---- - -# Our challenges - -- Common look & feel -- Common voice -- DRY: Don't Repeat Yourself -- Diagrams: what changes? -- Broken links -- Publishing - - ---- -