This project is a proof of concept experiment to see if docs as code can work for a particular set of technical documentation. This is one of a handful experiments to identify authoring tools and source content management system (SCM) for this content.
🧪The experiment🧪 prototype the content in the tooling, and then evaluate (score) the results against prioritized (weighted) requirements.
This is bogus draft material so I can evaluate the feasibility of using the MkDocs ↗ Markdown and Python static site generator and Material for MkDocs ↗ theme for my technical documentation.
With this project, I can understand if markdown and ssg meets my authoring, source code management, and deliverable generation requirements.
This project is intended for me (technical writer) and is likely not useful for others.
Before using POC MkDocs Tech Doc, ensure you have:
- Python
- Git
- Visual Studio Code (VSCode) with extensions: Python (MS), Code Spell checker, DevSkim (security analyzer), Markdown All in One, markdownlint, YAML (redhat)
- Material for MkDocs ↗ (use Python/pip) with plugins: glightbox, print-site
Use Material for Makedocs Getting Started ↗ Install and configure plugins:
Recommend using a Python virtual environment.
To create a virtual env (one time task):
- In Powershell or VS Code Terminal from the local repo folder,
python -m venv venv - Then
venv\Scripts\activate - You will see prompt now includes "venv" i.e.
(venv)C:\ProjectDir\<gitreponame> - Confirm you are running virtual env by checking pip version
pip --versionthe response should show pip from repo venv\Lib location.
With each VSCode session, activate virtual env. Type venv\Scripts\activate
Use live preview server. In Terminal, type mkdocs serve use the localhost:8000 port in the message.
Build the site. Type mkdocs build
For more information:
POC MkDocs Tech Doc is licensed under CC0 1.0 for this doc project only and provides no licensing provisions for the software it uses or any products that may appear in these draft materials.