Documentation portfolio: Olivier Carrère · Senior Technical Writer

Expertise

Areas of expertise

Each area links to the articles, case studies, and worked examples that demonstrate it.

• Docs-as-code

  Documentation in Git next to the product: branches, pull-request review, and repository design.

  See the evidence →

• DITA & structured authoring

  Topic-based DITA XML, content reuse with conrefs, and conditional text, including a product case study.

  See the evidence →

• Documentation architecture

  Information typing, modular content, repository structure, and consistent article templates.

  See the evidence →

• Developer & API documentation

  API reference templates, a machine-readable documentation API, and technical review with engineers.

  See the evidence →

• Automation & CI/CD

  Build, check, and publish pipelines, and content generated from data with Python and Jinja.

  See the evidence →

• AI-assisted documentation

  One part of the documentation workflow, always with human review: AI-assisted translation, a grounded documentation assistant, and a documentation API for AI agents.

  See the evidence →

Also: Documentation process & quality · Multilingual documentation

Selected work

Case studies and projects

• NuFirewall documentation

  Software product documentation in DITA XML, cited by the press as a strength of the product.

  Read the case study →

• This portfolio, as a docs-as-code project

  Bilingual documentation maintained in Git since 2014 and built by CI on every change.

  See how it is built →

• A machine-readable documentation API

  The same sources served to scripts and AI agents as llms.txt, Markdown, and JSON.

  Explore the API →

All selected work, with the expertise each project demonstrates, is on the Expertise page. To discuss a technical writing role or project, contact me on LinkedIn or see my professional profile ↗.

Start from your goal

What are you trying to do?

• Start a documentation project

  Define audience, scope, and deliverables before writing a single word.

  Define the project →

• Build a documentation process

  See the whole production chain, from information gathering to delivery.

  See the process →

• Adopt docs-as-code

  Manage documentation like code: version control, review, and CI/CD.

  Integrate docs with development →

• Choose an authoring model

  Decide how much structure your content needs, from Markdown to DITA.

  Compare the options →

• Improve an existing documentation system

  Audit what you have: orphaned pages, duplicates, and stale content.

  Run an audit →

• Automate documentation

  Build, check, and publish documentation automatically on every change.

  See a CI/CD pipeline →

Guided reading

Six paths through the manual

Read them in order for a complete method, or go straight to the path you need.

1. 01

   Understand documentation

   Why documentation architecture matters: value, maturity, information types.

   Read the foundations →
2. 02

   Build a documentation process

   The workflow step by step, from project definition to delivery.

   Follow the process →
3. 03

   Adopt docs-as-code

   Git, repository design, branches, CI/CD, and automated checks.

   Learn the workflow →
4. 04

   Choose an authoring model

   Structured authoring, DITA, Markdown, content reuse, and formats.

   Compare the models →
5. 05

   Build your toolkit

   Templates, checklists, and worked examples to reuse.

   Open the toolkit →
6. 06

   Automation & legacy techniques

   Jinja, Python, sed, Sphinx/ReST, XSL-FO: specialist and historical techniques.

   Explore the techniques →

Ready to use

Practical resources

Templates, checklists, and worked examples you can copy into your own project.

• Documentation quality checklist

  Run before merging any documentation change.

  Open the checklist →

• Docs-as-code workflow example

  One change, from branch to production, annotated step by step.

  Study the example →

• API documentation template

  One endpoint per page: method, parameters, request/response, error codes.

  Use the template →

• Documentation project plan template

  Goal, audience, scope, format, success criteria, timeline.

  Use the template →

AI documentation assistant

Explore the documentation

Describe what you need in your own words. Answers are generated from this portfolio’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.

Ask a question about the documentation

Ask

The assistant answers from the site's documentation only. It does not use general knowledge.

Try an example:

What is DITA XML?How does docs-as-code work?When should I use structured documentation?

Reference

Browse all documentation

Every page in the manual, grouped as in the navigation menu.

1. Understand documentation6 pages

• Overview
• Technical documentation: reduce costs, improve customer satisfaction
• The three levels of technical documentation
• From technical writing to technical communication
• Information types
• KISS Principle of Simplicity

2. Build a documentation process10 pages

• Overview
• Technical writing: an industrial process
• Project definition
• Gathering information
• Testing products to document them
• Content creation
• Validation and quality control
• Translation
• Delivery
• Managing a project from start to finish

3. Adopt docs-as-code11 pages

• Overview
• Integrating documentation into development processes
• Git
  • Version management systems - rustic but reliable
  • Git: from file to content
• Repository design
  • Repository
  • A single repository?
  • Which repository for group work?
  • Shared network directories - unsuitable for group work
  • SQL database
  • CMS: workflow as a bonus, but reliability to be tested
• Using branches in source management systems

4. Choose an authoring model11 pages

• Overview
• Structured authoring
  • Use structured authoring
  • Structured and unstructured formats
• DITA
  • Structured DITA XML format
  • Case studies in using DITA XML
  • Too complex a document architecture?
  • Case study: NuFirewall documentation
• From document to modular document base
• Source vs target formats
  • Source format
  • Target format
  • Formats and tools

5. Build your toolkit18 pages

• Overview
• Templates
  • Template: concept article
  • Template: task article
  • Template: reference article
  • Template: documentation project plan
  • Template: documentation review request
• Checklists
  • Checklist: documentation quality
  • Checklist: technical review
  • Checklist: documentation release readiness
  • Checklist: documentation migration
  • Checklist: docs-as-code adoption
  • Checklist: documentation audit
• Worked examples
  • Example: a well-structured Markdown page
  • Example: a documentation repository structure
  • Example: a basic docs-as-code workflow
  • Example: a documentation review workflow
  • Example: a practical CI/CD pipeline for documentation
• API documentation
  • Template: API documentation

6. Automation & legacy techniques11 pages

• Overview
• Jinja
  • Create different documents from the same sources using Jinja
  • Create different documents from the same sources via Jinja (object method)
  • Automatically insert data into a reStructuredText file
• Python
  • Regular expressions in Python
  • Auto-insert data into a DITA XML file
  • Automatically insert SQL data into a reStructuredText file
• sed: modify your text without opening your files
• Create different documents from the same ReST sources (conditional text)
• DITA XML and XSL-FO tutorials
• The Raspberry Pi 3 as a documentation platform

Explore the reference2 pages

• Explore the reference
• Glossary

Documentation API & AI2 pages

• Documentation API
• Ask the documentation

Documentation portfolio

By Olivier Carrère, Senior Technical Writer · Professional profile ↗

This site is Olivier Carrère's documentation portfolio: detailed expertise, methods, case studies, and technical evidence, from project definition to delivery. 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.