Doc site portfolio tutorial
Build a professional technical writing portfolio site using MkDocs and AI collaboration.
What you will learn
This tutorial shows you how to create a portfolio documentation site that showcases your software documentation skills, even if you do not have existing samples to share.
You will learn:
- How to set up a docs-as-code workflow with MkDocs
- How to collaborate with AI to generate different types of documentation
- How to create portfolio samples when you lack public work examples
- How to present AI-assisted work honestly and professionally
- How to deploy your site to GitHub Pages
Who this is for
This tutorial is designed for technical writers who:
- Need to create a software documentation portfolio
- Want to learn docs-as-code workflows
- Cannot share internal documentation from employers
- Want to demonstrate skills in API docs, tutorials, and reference content
- Are learning to collaborate effectively with AI tools
Tutorial steps
Follow these steps in order:
- Setup environment - Install MkDocs and configure your workspace
- Plan your site - Define portfolio goals and content strategy
- Generate structure - Create site navigation and templates
- Write content - Generate documentation samples with AI
- Refine with AI - Iterate and improve your content
- Deploy - Publish to GitHub Pages
Time required
- Initial setup and planning: 1-2 hours
- Content generation: 2-3 hours
- Refinement and deployment: 1-2 hours
- Total: 4-7 hours
Prerequisites
Before starting, verify you have:
- Basic Markdown knowledge
- GitHub account for deployment
- AI provider API key (Anthropic Claude or OpenAI)
- Text editor (VS Code, Cursor, or similar)
- Command line comfort
What you will build
A professional portfolio site featuring:
- About page with your technical writing background
- Documentation samples covering multiple types:
- API reference documentation
- Getting started guides
- Step-by-step tutorials
- How-to guides
- Conceptual explanations
- Troubleshooting guides
- CLI tool documentation
- Case study format explaining your approach to each sample
- Professional presentation suitable for job applications
Two paths available
This tutorial offers flexibility based on your needs:
Path A: Use the template - Start with a pre-configured MkDocs site and focus on content creation
Path B: Build from scratch - Learn the complete setup process and customize everything
Both paths teach the same AI collaboration techniques and produce similar results. Choose based on your learning goals and time available.