Skip to content

Commit 42b17f5

Browse files
DeeprajPandeyDeeprajPandey
committed
docs: add contributing guidelines, documentation templates, and reorganise readme
1 parent 5adb6c3 commit 42b17f5

3 files changed

Lines changed: 265 additions & 53 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing to Makerspace Docs
2+
3+
:tada: First off, thanks for taking the time to help improve our documentation!
4+
5+
## Code of Conduct
6+
7+
This project and everyone participating in it is governed by the [Makerspace Code of Conduct](https://github.com/Makerspace-Ashoka/policies/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behaviour to [[email protected]](mailto:[email protected]).
8+
9+
## Quick Start
10+
11+
1. Install Node.js (if you haven't already). [Here's a good guide on how to do this using nvm](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment#installing_node).
12+
2. Fork the repository
13+
3. Clone and setup:
14+
```bash
15+
git clone https://github.com/[YOUR_USERNAME]/docs.git
16+
cd docs
17+
npm install
18+
npm start
19+
```
20+
4. See a local copy of the site live at `http://localhost:3000`
21+
22+
That's it! The dev server auto-refreshes as you edit.
23+
24+
## Making Changes
25+
26+
1. Create a new branch (choose a descriptive branch name, like `feat/voron-guide`)
27+
```bash
28+
git checkout -b [NEW_BRANCH_NAME]
29+
git push origin [NEW_BRANCH_NAME]
30+
```
31+
2. Edit markdown files in `docs/`
32+
3. Check your changes look good in the browser
33+
4. Commit with a clear message: `git commit -m "feat: add Voron 2.4 setup guide"`
34+
5. Push to your fork:
35+
```bash
36+
git push
37+
```
38+
6. Open a Pull Request on this [repository](https://github.com/Makerspace-Ashoka/docs/pulls).
39+
40+
## Project Structure
41+
42+
```
43+
docs/ # All documentation content
44+
blog/ # Blog posts
45+
static/img/ # Images and assets
46+
src/components/ # Custom React components
47+
docusaurus.config.js # Site configuration
48+
```
49+
50+
## Development Workflow
51+
52+
### Branch Naming
53+
- `feat/description` - New features or content
54+
- `fix/description` - Bug fixes
55+
- `docs/description` - Documentation meta-changes
56+
- `refactor/description` - Restructuring
57+
58+
### Testing Checklist
59+
- [ ] `npm run build` succeeds
60+
- [ ] No broken links
61+
- [ ] Images load correctly
62+
- [ ] Mobile responsive
63+
- [ ] No console errors
64+
65+
## Commit Messages (Accepted but not recommended)
66+
67+
Keep it simple and descriptive:
68+
- ✅ `Add safety guidelines for laser cutting`
69+
- ✅ `Fix broken images in 3D printing guide`
70+
- ✅ `Update Ender 3 troubleshooting section`
71+
- ❌ `update stuff`
72+
- ❌ `changes`
73+
74+
## Conventional Commits (Recommended)
75+
76+
We recommend using [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)for all your commit messages.
77+
78+
Format: `<type>(<scope>): <description>`
79+
80+
**Types:**
81+
- `feat` - New content or features
82+
- `fix` - Corrections
83+
- `docs` - Meta-documentation
84+
- `style` - Formatting only
85+
- `refactor` - Restructuring
86+
- `chore` - Maintenance
87+
88+
**Scopes (optional):**
89+
- `equipment`, `training`, `safety`, `getting-started`
90+
91+
Examples:
92+
```
93+
feat(equipment): add Voron 2.4 guide
94+
fix(safety): correct fire extinguisher locations
95+
docs: update contributing guidelines
96+
```
97+
## Writing Tips
98+
99+
- Write clearly and simply
100+
- Use images when helpful (put them in `static/img/`)
101+
- Test all your links
102+
- Check spelling (we use British English)
103+
104+
## Need Help?
105+
106+
- Not sure where to start? Check the [Issues](link) page for "good first issue" tags
107+
- Questions? Open a discussion or ask on the community google chat
108+
- Want quick tasks? See our "Leave Your Mark" page
109+
110+
## Building
111+
112+
Most contributors don't need this, but if you want to test the production build:
113+
```bash
114+
npm run build
115+
```
116+
117+
---
118+
119+
That's really all you need to know! For more detailed guidelines, see [WRITING_TEMPLATES.md](./WRITING_TEMPLATES.md)

‎README.md‎

Lines changed: 65 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,64 @@
1-
# Makerspace Docs
1+
# Makerspace Documentation
22

3-
## Current sitemap (overview)
3+
Documentation site for the [Makerspace](https://www.ashoka.edu.in/digital-makerspace/) under the [Mphasis AI & Applied Tech Lab at Ashoka](https://www.ashoka.edu.in/page/mphasis-lab/).
4+
5+
## What's Inside
6+
7+
- **Equipment guides** - 3D printers, woodworking tools, electronics, textiles, drones, and more
8+
- Training resources - Certifications and tutorials
9+
- Safety protocols - Keep everyone safe
10+
- Leave Your Mark - Ways to contribute to the makerspace community
11+
12+
## Quick Start
13+
14+
```bash
15+
npm install
16+
npm start
417
```
5-
├── Home
6-
├── Getting Started
7-
├── Equipment
8-
├── Training & Certifications
9-
├── Leave Your Mark
10-
├── Resources
11-
├── Policies & Safety
12-
└── Blog
18+
19+
Opens at http://localhost:3000 with live reload.
20+
21+
## Contributing
22+
23+
We'd love your help! Whether you're fixing a typo or documenting equipment:
24+
25+
1. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
26+
2. Check [WRITING_TEMPLATES.md](./WRITING_TEMPLATES.md) for documentation templates
27+
3. Browse [Issues](https://github.com/Makerspace-Ashoka/docs/issues) for tasks tagged "good first issue"
28+
4. Visit our ["Leave Your Mark"](#) page for quick contribution ideas
29+
30+
## Project Structure
31+
1332
```
33+
docs/ # All documentation content
34+
static/img/ # Images and assets
35+
blog/ # Announcements and updates
36+
```
37+
38+
See the [detailed sitemap](#sitemap) below for full content structure.
39+
40+
## Build & Deploy
1441

15-
## Detail Sitemap
42+
```bash
43+
npm run build # Generate static site
44+
npm run serve # Preview production build locally
45+
```
46+
47+
**Deploy to GitHub Pages:**
48+
```bash
49+
GIT_USER=<username> npm run deploy
50+
```
51+
52+
## Tech Stack
53+
54+
Built with [Docusaurus](https://docusaurus.io/) - a modern static site generator optimised for documentation.
55+
56+
---
57+
58+
## Sitemap
59+
60+
<details>
61+
<summary>Click to expand full site structure</summary>
1662

1763
```
1864
docs.makerspace.../
@@ -63,13 +109,13 @@ docs.makerspace.../
63109
│ ├── Self-Paced Tutorials
64110
│ ├── Required Certifications
65111
│ └── Safety Quizzes
66-
├── Leave Your Mark/
67-
│ ├── Overview (why contribute, impact stories)
112+
├── Leave Your Mark
113+
│ ├── Overview
68114
│ ├── Current Opportunities
69115
│ │ ├── Quick Wins (< 1 hour)
70116
│ │ ├── Mini Projects (1-4 hours)
71-
│ │ └── Ongoing Initiatives (recurring/long-term)
72-
└── Hall of Fame (contributor recognition)
117+
│ │ └── Ongoing Initiatives
118+
│ └── Hall of Fame
73119
├── Resources
74120
│ ├── Tutorials & Guides
75121
│ ├── Material Specifications
@@ -80,45 +126,11 @@ docs.makerspace.../
80126
│ ├── Emergency Procedures
81127
│ ├── Equipment-Specific Safety
82128
│ └── Material Handling
83-
└── Blog (for updates/announcements)
84-
```
85-
86-
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
87-
88-
## Installation
89-
90-
```bash
91-
yarn
92-
```
93-
94-
## Local Development
95-
96-
```bash
97-
yarn start
98-
```
99-
100-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
101-
102-
## Build
103-
104-
```bash
105-
yarn build
106-
```
107-
108-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
109-
110-
## Deployment
111-
112-
Using SSH:
113-
114-
```bash
115-
USE_SSH=true yarn deploy
129+
└── Blog
116130
```
117131

118-
Not using SSH:
132+
</details>
119133

120-
```bash
121-
GIT_USER=<Your GitHub username> yarn deploy
122-
```
134+
## License
123135

124-
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
136+
This repository is covered under the Apache 2.0 license, see [LICENSE](./LICENSE).

‎WRITING_TEMPLATES.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Writing Templates
2+
3+
## Equipment Documentation Template
4+
5+
```markdown
6+
---
7+
sidebar_position: 1
8+
---
9+
10+
# Equipment Name
11+
12+
One-line description.
13+
14+
## Specifications
15+
- **Model:**
16+
- **Location:**
17+
- **Certification Required:** Yes/No
18+
19+
## Getting Started
20+
[Quick start guide]
21+
22+
## Safety
23+
:::danger
24+
Critical safety info
25+
:::
26+
27+
## Common Tasks
28+
### Task Name
29+
Steps...
30+
31+
## Troubleshooting
32+
Common issues and solutions
33+
```
34+
35+
## Style Guide
36+
37+
- Use active voice: "Click the button" not "The button should be clicked"
38+
- Address reader as "you"
39+
- Present tense: "The printer heats" not "will heat"
40+
- Be specific: include model numbers, measurements
41+
42+
## Markdown Features
43+
44+
### Admonitions
45+
```markdown
46+
:::note
47+
Standard note
48+
:::
49+
50+
:::tip
51+
Helpful tip
52+
:::
53+
54+
:::warning
55+
Pay attention
56+
:::
57+
58+
:::danger
59+
Safety critical
60+
:::
61+
```
62+
63+
### Code Blocks
64+
````markdown
65+
```python
66+
print("Hello!")
67+
```
68+
````
69+
70+
### Images
71+
```markdown
72+
![Description](/img/path/to/image.jpg)
73+
```
74+
75+
## Advanced Tasks
76+
77+
### Adding a New Section
78+
1. Create folder in `docs/`
79+
2. Add `_category_.json` with metadata
80+
3. Update `sidebars.js` if needed
81+

0 commit comments

Comments
 (0)