Engineering Handbook

Engineering OS — The Open Engineering Study System

Engineering OS is an open-source learning system designed for software engineers and computer science students.

It combines structured engineering documentation, diagrams, learning roadmaps, and interview preparation into a single knowledge system built using MkDocs.

The goal is to create a long-term engineering reference similar to professional engineering handbooks, but fully open, searchable, and continuously improving.

• Structured Computer Science documentation
• MkDocs + Material for MkDocs documentation system
• Interactive Mermaid diagrams
• Engineering concept explanations with examples
• Searchable documentation
• Dark mode support
• Interview preparation resources
• Beginner-friendly contribution workflow

• MkDocs
• Material for MkDocs
• Markdown
• Mermaid diagrams
• GitHub Pages
• Docker

Run the documentation site locally using Docker:

docker compose up --build

The site will be available at:

http://localhost:8000

Engineering OS can be run locally using Docker (recommended) or Python.

Using Docker ensures a consistent environment and avoids dependency conflicts.

• Docker Desktop or Docker Engine

docker compose up --build

The documentation will be available at:

http://localhost:8000

docker compose down

If you prefer running the project without Docker.

• Python 3.10+
• pip

python -m venv .venv

Activate the environment:

Windows (PowerShell)

.venv\Scripts\Activate.ps1

macOS / Linux

source .venv/bin/activate

pip install -r requirements.txt

mkdocs serve

If mkdocs is not available in your PATH:

python -m mkdocs serve

Open the URL shown in the terminal.

mkdocs build

The generated site will be inside the site/ directory.

mkdocs.yml              # Site configuration
docs/                   # Documentation content
docs/stylesheets/       # Custom CSS
docs/diagrams/          # Diagram assets
.github/workflows/      # CI/CD pipelines
docker-compose.yml      # Docker setup

The project uses GitHub Actions to automatically build and deploy the documentation.

Workflow overview:

• Pull Requests trigger a documentation build check
• If the build succeeds, the PR can be merged
• Merges to main automatically deploy the documentation to GitHub Pages

Contributions are welcome.

Engineering OS is actively being developed and improved, and contributions from the community are encouraged.

You can contribute by:

• adding new engineering topics
• improving explanations
• adding diagrams
• fixing typos
• improving examples

Even small improvements are appreciated.

If you are new to Git or open source, follow these steps.

Click Fork on GitHub to create your own copy.

git clone https://github.com/YOUR_USERNAME/engineering-os.git
cd engineering-os

git checkout main
git pull origin main
git checkout -b feature/<short-name>

Edit documentation, add explanations, or improve examples.

git add .
git commit -m "Describe your change"

git push origin feature/<short-name>

Go to GitHub and open a Pull Request from your branch to main.

After review, the changes can be merged into the project.

Engineering OS is an actively evolving project.

The documentation structure, topics, and learning resources are continuously improving as the project grows.

Feedback, ideas, and contributions are always welcome.

This project is licensed under the MIT License.

See the LICENSE file for details.