Olivier Carrère · Senior Technical Writer: Technical writing practice
A documentation portfolio and library: methods, case studies, worked examples, and documentation projects, in English and French, maintained in Git since 2014.
Docs-as-code · DITA & structured authoring · Documentation architecture · Developer & API documentation · Automation & CI/CD
Available for a new opportunity from October 2026
Follow the six sequential paths for a complete, end-to-end documentation methodology.
Looking for something specific? Use search (⌘K), browse by topic, by information type or jump to your goal.
Guided reading
Six paths through the manual
Read them in order for a complete method, or go straight to the path you need.
Understand documentation
Why documentation architecture matters: value, maturity, information types.
Build a documentation process
The workflow step by step, from project definition to delivery.
Adopt docs-as-code
Git, repository design, branches, CI/CD, and automated checks.
Choose an authoring model
Structured authoring, DITA, Markdown, content reuse, and formats.
Build your toolkit
Templates, checklists, and worked examples to reuse.
Automation & legacy techniques
Jinja, Python, sed, Sphinx/ReST, XSL-FO: specialist and historical techniques.
Selected work
Case studies and projects
Software product documentation in DITA XML, cited by the press as a strength of the product.
Bilingual documentation maintained in Git since 2014 and built by CI on every change.
The same sources served to scripts and AI agents as llms.txt, Markdown, and JSON.
Site history
How the documentation evolved
Explore how commits shaped the documentation portfolio: each change flows into an area of the manual, then into its pages.
Simplified diagram of the site's Git history, from commit to documentation area to page: 4 commits flow into 3 areas (2. Build a documentation process, 4. Choose an authoring model, 6. Automation & legacy techniques), then into 5 pages (Validation and quality control, Managing a project from start to finish, Structured and unstructured formats, From document to modular document base, sed: modify your text without opening your files). The width of each flow is the number of documentation files changed.
Expertise
Areas of expertise
Each area links to the articles, case studies, and worked examples that demonstrate it.
Documentation in Git next to the product: branches, pull-request review, and repository design.
Topic-based DITA XML, content reuse with conrefs, and conditional text, including a product case study.
Information typing, modular content, repository structure, and consistent article templates.
API reference templates, a machine-readable documentation API, and technical review with engineers.
Build, check, and publish pipelines, and content generated from data with Python and Jinja.
One part of the documentation workflow, always with human review: AI-assisted translation, a grounded documentation assistant, and a documentation API for AI agents.
Start from your goal
What are you trying to do?
Define audience, scope, and deliverables before writing a single word.
See the whole production chain, from information gathering to delivery.
Manage documentation like code: version control, review, and CI/CD.
Decide how much structure your content needs, from Markdown to DITA.
Audit what you have: orphaned pages, duplicates, and stale content.
Build, check, and publish documentation automatically on every change.
Ready to use
Practical resources
Templates, checklists, and worked examples you can copy into your own project.
Run before merging any documentation change.
One change, from branch to production, annotated step by step.
One endpoint per page: method, parameters, request/response, error codes.
Goal, audience, scope, format, success criteria, timeline.
AI documentation assistant
Explore the documentation
Describe what you need in your own words. Answers are generated from this site’s content only, with links to the pages they drew on. To use the content in your own tools or agents, see the documentation API.
Answer
Sources & Further Reading
Find & Browse
Browse all documentation
Access documentation through three complementary paths: follow the 6 learning paths, look up by information type, or explore by topic.
1. Understand documentation6 pages
2. Build a documentation process10 pages
3. Adopt docs-as-code11 pages
4. Choose an authoring model11 pages
- Overview
- Structured authoring
- DITA
- From document to modular document base
- Source vs target formats
5. Build your toolkit18 pages
- Overview
- Templates
- Checklists
- Worked examples
- API documentation
6. Automation & legacy techniques11 pages
Explore the reference3 pages
Documentation API & AI2 pages
ConceptIdeas, principles, architecture, and mental models to understand the subject.32 pages
- A single repository?3. Adopt docs-as-codeRepository designGitVersion control
- Case studies in using DITA XML4. Choose an authoring modelDITADITA XMLTranslation
- CMS: workflow as a bonus, but reliability to be tested3. Adopt docs-as-codeRepository designVersion control
- Content creation2. Build a documentation processTechnical writing
- Delivery2. Build a documentation processTechnical writingCI/CD
- Formats and tools4. Choose an authoring modelSource vs target formatsDITA XMLStructured authoring
- From document to modular document base4. Choose an authoring modelDITA XMLStructured authoring
- From technical writing to technical communication1. Understand documentationTechnical writing
- Gathering information2. Build a documentation processTechnical writing
- Git: from file to content3. Adopt docs-as-codeGitGitVersion control
- Information types1. Understand documentationDITA XMLStructured authoring
- Integrating documentation into development processes3. Adopt docs-as-codeGitDocs-as-code
- KISS: keeping technical documentation simple1. Understand documentationTechnical writingContent reuse
- Managing a project from start to finish2. Build a documentation processGit
- Project definition2. Build a documentation processTechnical writingDocumentation planning
- Repository3. Adopt docs-as-codeRepository designGitVersion control
- Shared network directories - unsuitable for group work3. Adopt docs-as-codeRepository designVersion control
- Source format4. Choose an authoring modelSource vs target formatsTechnical writingStructured authoring
- SQL databases as documentation repositories3. Adopt docs-as-codeRepository designVersion control
- Structured and unstructured formats4. Choose an authoring modelStructured authoringDITA XMLStructured authoring
- Structured DITA XML format4. Choose an authoring modelDITA
- Target format4. Choose an authoring modelSource vs target formatsTechnical writingPublishing
- Technical documentation: reduce costs, improve customer satisfaction1. Understand documentation
- Technical writing: an industrial process2. Build a documentation process
- Testing products to document them2. Build a documentation processTechnical writing
- The three levels of technical documentation1. Understand documentationTechnical writingStructured authoring
- Too complex a document architecture?4. Choose an authoring modelDITADITA XMLStructured authoring
- Translation2. Build a documentation processTranslation
- Using branches in source management systems3. Adopt docs-as-codeGitVersion control
- Validation and quality control2. Build a documentation processTechnical writingCI/CD
- Version management systems - rustic but reliable3. Adopt docs-as-codeGitGitVersion control
- Which repository for group work?3. Adopt docs-as-codeRepository designVersion control
TaskStep-by-step procedures and concrete workflows toward a verifiable outcome.15 pages
- Auto-insert data into a DITA XML file6. Automation & legacy techniquesPythonDITA XMLPython
- Automatically insert data into a reStructuredText file6. Automation & legacy techniquesJinjaPythonAutomation
- Automatically insert SQL data into a reStructuredText file6. Automation & legacy techniquesPythonPythonAutomation
- Automation & legacy techniques6. Automation & legacy techniques
- Create different documents from the same ReST sources (conditional text)6. Automation & legacy techniquesAutomationreStructuredText
- Create different documents from the same sources using Jinja6. Automation & legacy techniquesJinjaPythonAutomation
- Create different documents from the same sources via Jinja (object method)6. Automation & legacy techniquesJinjaPythonAutomation
- DITA XML and XSL-FO tutorials6. Automation & legacy techniquesDITA XMLTranslation
- Example: a basic docs-as-code workflow5. Build your toolkitWorked examplesDocs-as-codeCI/CD
- Example: a documentation review workflow5. Build your toolkitWorked examplesDocumentation review
- Example: a practical CI/CD pipeline for documentation5. Build your toolkitWorked examplesDocs-as-codeCI/CD
- Example: a well-structured Markdown page5. Build your toolkitWorked examplesMarkdownInformation typing
- Regular expressions in Python6. Automation & legacy techniquesPythonPythonAutomation
- sed: modify your text without opening your files6. Automation & legacy techniquesAutomation
- The Raspberry Pi 3 as a documentation platform6. Automation & legacy techniquesPythonAutomation
ReferenceStructured lookup facts, syntax, specifications, parameters, and checklists.18 pages
- MarkdownAPI documentation
- Build your toolkit5. Build your toolkit
- Case study: NuFirewall documentation4. Choose an authoring modelDITADITA XMLTranslation
- Checklist: docs-as-code adoption5. Build your toolkitChecklistsDocs-as-codeCI/CD
- Checklist: documentation audit5. Build your toolkitChecklistsQuality assurance
- Checklist: documentation migration5. Build your toolkitChecklistsDITA XMLDocumentation migration
- Checklist: documentation quality5. Build your toolkitChecklistsQuality assurance
- Checklist: documentation release readiness5. Build your toolkitChecklistsTranslationQuality assurance
- Checklist: technical review5. Build your toolkitChecklistsDocumentation review
- Example: a documentation repository structure5. Build your toolkitWorked examplesDocs-as-codeTranslation
- Template: API documentation5. Build your toolkitAPI documentationMarkdownAPI documentation
- Template: concept article5. Build your toolkitTemplatesMarkdownInformation typing
- Template: documentation project plan5. Build your toolkitTemplatesDocumentation planning
- Template: documentation review request5. Build your toolkitTemplatesDocumentation review
- Template: reference article5. Build your toolkitTemplatesMarkdownInformation typing
- Template: task article5. Build your toolkitTemplatesMarkdownInformation typing
Browse documentation across the 21 controlled-vocabulary topics:
- Technical writing12 pagesC12
- DITA XML10 pagesC6T2R2
- Automation9 pagesT9
- Version control9 pagesC9
- Git8 pagesC7T1
- Markdown8 pagesC2T1R5
- Translation8 pagesC4T1R3
- Docs-as-code7 pagesC3T2R2
- Python7 pagesT7
- Structured authoring7 pagesC7
- CI/CD6 pagesC3T2R1
- Information typing6 pagesC2T1R3
- reStructuredText6 pagesT6
- Conditional text5 pagesT4R1
- Documentation review5 pagesC1T2R2
- Publishing5 pagesC2T3
- Quality assurance5 pagesC1T1R3
- Content reuse4 pagesC3R1
- API documentation3 pagesC1R2
- Documentation migration2 pagesC1R1
- Documentation planning2 pagesC1R1
Release milestones
Releases of the whole site, tagged in its Git repository.
Technical writing portfolio repositioning
Repositions the site as Olivier Carrère's senior technical writer portfolio, with a task-oriented homepage and a recruiter-friendly Expertise page.
Builds on the editorial design system, the 2026 EN/FR content audit and the new six-section navigation.
Information architecture and documentation platform
Introduces an information architecture organised around reader goals and restructures every article into concept, task or reference pages, with a practical toolkit and glossary.
Adds a static documentation API (llms.txt, JSON index, schema.json, field selection and pagination), the Ask the documentation assistant and the Documentation Explorer.
Astro + Starlight migration
Replaces the Sphinx/reStructuredText build with an Astro + Starlight site whose content is authored in Markdown/MDX (merge of PR #2). This is the foundation of the current site and the first release after the 1.x Sphinx line.
At this commit the legacy reStructuredText sources are still in the tree; the Astro project moved to the repository root and the content conversion was completed in the commits that follow.
How this documentation evolved. These releases cover only the latest stage: before them, the same body of documentation moved from a WordPress blog to a Sphinx site in reStructuredText, then to today’s Astro and Starlight portfolio. Explore the site history
This site is Olivier Carrère's technical writing practice: a practical guide to designing, writing, maintaining, and publishing technical documentation, based on his methods, projects, and experience. His professional profile presents his background, selected work, and articles.
Whether you're choosing between DITA XML and Markdown, migrating to a docs-as-code workflow, or integrating documentation into a CI/CD pipeline — these guides cover the methods, formats, and tools that make technical documentation a sustainable, scalable engineering practice.