Skip to content

Step 2: Plan your site

Define your portfolio strategy before creating content.

Complete these tasks

By the end of this step, you will have:

  • Clear portfolio goals documented
  • List of documentation types to create
  • Topics selected for each sample
  • Understanding of your target audience

Time estimate

30-45 minutes

Define your portfolio goals

Answer these questions to clarify your objectives. Write your answers in a planning document (create docs/planning.md or use a separate note).

What job roles are you targeting?

Examples: - Technical writer at software companies - API documentation specialist - Developer experience (DevEx) writer - Documentation engineer - Content strategist for developer tools

Your answer helps determine which documentation types to emphasize.

What industries interest you?

Examples: - SaaS platforms - Developer tools - Cloud infrastructure - Financial technology - Healthcare technology

Your answer guides topic selection for samples.

What skills do you want to demonstrate?

Check all that apply:

  • Writing for developer audiences
  • API documentation expertise
  • Docs-as-code workflows
  • Information architecture
  • Technical accuracy
  • Clear explanations of complex topics
  • Tutorial design
  • Troubleshooting content creation
  • Command-line tool documentation

Choose documentation types to create

Select 3-5 different types to demonstrate versatility. Include at least one from each category.

Reference documentation

  • API reference: Endpoints, parameters, responses
  • CLI reference: Commands, flags, examples
  • Configuration reference: Settings, options, formats

Choose reference if: You want to show precision, attention to detail, and structured thinking.

Task-oriented content

  • Getting started guide: First-time user onboarding
  • How-to guides: Single-task instructions
  • Step-by-step tutorials: Multi-step learning experiences

Choose task-oriented if: You want to show user empathy and instructional design skills.

Explanatory content

  • Conceptual guides: Architecture, design patterns, theory
  • Best practices: Recommendations and guidelines
  • Comparison guides: Feature comparisons, decision matrices

Choose explanatory if: You want to show ability to clarify complex topics.

Support content

  • Troubleshooting guides: Common problems and solutions
  • FAQ: Frequently asked questions
  • Error reference: Error codes and resolutions

Choose support if: You want to show problem-solving and user support skills.

Select topics for your samples

You need realistic topics to document. Use one of these approaches:

Approach 1: Document open source tools you use

Document tools you already know:

  • Text editors (VS Code extensions, Vim plugins)
  • Command-line utilities (git commands, package managers)
  • Development frameworks (React hooks, Python libraries)
  • Build tools (Webpack configs, Docker commands)

Advantages: - Authentic knowledge - Can verify accuracy - Demonstrates real tool expertise

Considerations: - Check if good documentation already exists - Focus on underserved areas or new features - Explain this is "practice documentation" in your portfolio

Approach 2: Create documentation for fictional products

Invent realistic but fictional tools:

  • "CloudDeploy API" - fictional cloud deployment service
  • "DataFlow CLI" - fictional data pipeline tool
  • "SecureAuth SDK" - fictional authentication library

Advantages: - Complete creative control - No conflicting official docs - Show design thinking from scratch

Considerations: - Must be realistic and detailed - Explain clearly that products are fictional - Demonstrate authentic technical depth

Approach 3: Document your own projects

Document tools or scripts you have built:

  • Personal automation scripts
  • Side project APIs
  • Open source contributions
  • Portfolio site itself (meta-documentation)

Advantages: - Genuine subject matter expertise - Can share code repositories - Shows both technical and writing skills

Considerations: - Projects should be substantial enough - Code should be clean and shareable - Documentation must match real project complexity

Plan your documentation samples

Create a planning table. For each sample, define:

Documentation type Topic Approach Target audience Purpose
API reference CloudDeploy REST API Fictional product Backend developers Show API doc structure
Getting started Docker basics Open source tool New Docker users Show tutorial design
CLI reference git advanced commands Open source tool Experienced developers Show reference precision

Your table helps ensure variety and demonstrates strategic thinking.

Understand your audience

Your portfolio has two audiences:

Primary: Hiring managers and recruiters

They want to see: - Professional presentation - Range of documentation types - Technical accuracy - Clear communication - Attention to detail

Optimize for: Easy scanning, clear structure, professional polish

Secondary: Documentation team members

They want to see: - Documentation tooling knowledge (MkDocs, Markdown, Git) - Docs-as-code workflow understanding - Collaboration potential - Problem-solving approach

Optimize for: Technical depth, process explanations, tool familiarity

Document your approach to AI collaboration

Write down how you plan to use AI for this portfolio. This becomes part of your case studies.

Example documentation:

## How I used AI for this sample

**Tool**: Claude 3.5 Sonnet via Anthropic API

**Process**:
1. Created detailed outline of API endpoints
2. Drafted initial descriptions with AI
3. Reviewed for technical accuracy
4. Revised based on user testing
5. Refined tone and formatting

**AI contribution**: Approximately 40% generation, 60% human editing

**What I did manually**:
- All technical accuracy verification
- Information architecture
- Code example creation
- Final editing and polish

Being transparent about AI use demonstrates: - Honesty and integrity - Modern workflow understanding - Critical thinking skills - Editing and revision abilities

Set up your profile file

The content generation scripts use a profile YAML file to personalize the content they generate. Set it up now so it is ready for Step 3.

Copy the example profile and open it for editing:

# From the docs-automation-examples/ root directory
cp 02-doc-site-portfolio/profile.example.yaml 02-doc-site-portfolio/profile.yaml

Open profile.yaml and fill in your details:

  • name, title, years_experience
  • specialties — documentation types you focus on
  • tools — tools you use (MkDocs, Confluence, Git, etc.)
  • experience — work history with concrete highlights
  • approach — your documentation philosophy in one or two sentences
  • contact — email and LinkedIn
  • projects — documentation projects you want to showcase

You do not need to complete every field now. Fill in what you know and return to it as you go. The more detail you provide, the more personalized the generated content will be.

profile.yaml is listed in .gitignore and will not be committed.

Create your planning document

Create docs/planning.md with this template:

# Portfolio Planning

## Goals

**Target roles**: [List 2-3 specific job titles]

**Target industries**: [List 2-3 industries]

**Key skills to demonstrate**: [List 3-5 skills]

## Documentation samples

| Type | Topic | Approach | Audience | Purpose |
|------|-------|----------|----------|---------|
| [Type] | [Topic] | [Open source/Fictional/Own project] | [Audience] | [Purpose] |

## AI collaboration approach

**Primary AI tool**: [Anthropic Claude / OpenAI GPT]

**Use cases**:
- Initial content generation
- Content improvement suggestions
- Example code creation
- Editing and refinement

**Human oversight**:
- Technical accuracy verification
- Information architecture
- Tone and voice
- Final quality control

## Timeline

**Week 1**: Setup and planning
**Week 2**: Create 2-3 documentation samples
**Week 3**: Refine content and deploy

Summary

You completed these tasks:

  • ✓ Defined clear portfolio goals
  • ✓ Selected 3-5 documentation types to create
  • ✓ Chose topics and approaches for each sample
  • ✓ Planned AI collaboration strategy
  • ✓ Created planning document

Example planning output

Here is a complete example:

Goals: Target technical writer roles at developer tool companies, emphasizing API documentation and developer experience.

Samples planned: 1. API reference for fictional "EventStream API" (webhook service) 2. Getting started guide for open source tool (MkDocs) 3. CLI reference for custom deployment tool (own project) 4. Troubleshooting guide for Docker (open source) 5. Conceptual guide on API versioning strategies (fictional context)

AI approach: Use Claude for initial drafts, human oversight for technical accuracy and examples, transparent documentation of process in case studies.

Next step: Generate structure