Skip to content

justwriteclick/docs-like-code-stories

Repository files navigation

docs-like-code-stories

Collection of use cases for Docs Like Code.

There are great stories out there; let's make them accessible to everyone.

The vision here is to provide the spark for more teams to think about their documentation in new ways. Read about automation, reviews, integration points, and get inspired to try some small changes yourself.

Send in a Pull Request for review, writing in Markdown. Use any headings you want, but an outline could be:


# Use Case: <company or organization name>

## What we build

## Why we chose these techniques

## Audience considerations

## Reviews

## Publishing

## Automation

## Version control and workflow

## Benefits

## Cautionary tales

## What you wish you knew

Let's get these stories out into the world!

General questions for each use case

What site or sites do you create from a repository source? What are the repositories that build the deliverables? Can you give an idea of the size, such as how many pages (source and output)? If they're private, that's fine too, talk about what led to that decision.

What factors led your team to choose a development approach for docs? Why and when was it chosen?

What type of audience are you writing for? Do your readers write with you? If so, how?

How active is your review queue? How often do you publish?

Is your version control system "pessimistic" with single checkouts and file locking? Or is it "optimistic" with multiple people working on the same files at the same time? Do you merge or rebase? Have you kept the same workflow always? How long has the workflow been in place?

What's your biggest win from using a developer workflow for docs? Tell a story.

What would you warn others about when thinking about using development tools and workflows for docs?

Would you suggest migrating content or only building new in this system?

Do you have automation? If so, what type or tooling, and where is the automation in the workflow?

Are there any questions you wish you had asked before treating docs like code?

Releases

No releases published

Packages

No packages published