Refract

A fictional JavaScript UI framework created to sharpen your technical documentation skills.

What is Refract?

Refract is a fictional, React-inspired JavaScript framework designed to give technical writers a playground for building rich and structured documentation. It introduces concepts like refractions, lenses, and optics to simulate a complex, modern front-end library.

This project was created and maintained by the Technical Writers Mentorship Program (TWMP) to help writers practice real-world documentation workflows.

Why did we create this project?

Documenting a real-world product often involves:

• Explaining complex concepts clearly
• Writing step-by-step guides for setup and usage
• Structuring information for different personas (beginner, advanced, contributor, etc.)
• Maintaining consistency and clarity across documentation

Refract simulates all of that in one fictional but detailed framework.

How to use this repo

1. Understand the project: Navigate to the Refract project file to get a good understanding of how this project works.

2. Fork this repository: This gives you your own workspace to build documentation.

3. Document the framework

4. Enhance the fictional project (optional, encouraged!): You can:

   • Add new APIs
   • Simulate internal logic
   • Create new folders like plugins/, router/, or compiler/

5. Share your work with the community: Drop your fork link in the TWMP community Discord or tag us on social media. We love to see creative spins!

Core concepts (Brief overview)

Concept	Description
Refractions	Reactive state units similar to signals or stores
Lenses	Scope-aware helpers for accessing props, effects, and state
Optics	Composable logic units like hooks
Components	Pure functions that return UI using JSX-like syntax
Effects	Side-effect handlers (useEffect, useFlash)
createApp()	Initializes and mounts the app
createComponent()	Builds a functional component

Want more technical details? We recommend building the docs for each one! 😉

An example structure you could use:

docs/
├── getting-started.md
├── concepts/
│   ├── refractions.md
│   ├── lenses.md
│   └── optics.md
├── api/
│   ├── createComponent.md
│   ├── useRefraction.md
│   └── useEffect.md
├── tutorials/
│   ├── counter-app.md
│   └── global-theme.md
└── contributing.md

Don't constrain yourself to this structure. Please be as flexible as possible and rely on diverse SSGs to bring this project to life.

Tips for writers

• Write as if this project is used by thousands of developers.
• Clarify what problems each concept/API solves.
• Show code examples on every page.
• Structure your docs like a real developer site (e.g. React, Vue, or Svelte).
• You can even create a mock website using tools like Docusaurus, VuePress, or Astro.

A project by TWMP

This project was created by the Technical Writers Mentorship Program, an open community for mentoring and growing the next generation of technical writers.

We hope Refract gives you the space to explore, create, and get hands-on experience with the art of writing developer documentation.