Writing standards
General .md standards for OpenBlog
Use this guide to keep every post clear, consistent, and useful for readers.
These standards apply to new posts and updates to existing posts.
Recommended post flow
- Start with a short intro: what problem this post solves and who it is for.
- Use clear section headings (
##, ###) to break concepts into steps. - Add at least one practical example (command, code, configuration, or scenario).
- Add at least one trusted reference when making factual or version-specific claims.
- End with a short summary or action checklist.
Markdown formatting rules
- Use one
# heading as the title in content body only when needed; prefer starting body at ## sections. - Keep paragraphs short (2 to 4 lines) for easier scanning.
- Use fenced code blocks with language labels (for example
bash, js, ts). - Use bullet lists for grouped ideas and numbered lists for ordered procedures.
- Write links with clear labels, not raw "click here" text.
Strong example
## Why connection pooling matters
Creating a new database connection for every request is expensive.
### Practical setup
Use a shared pool and set a max connection limit based on your DB size.
```ts
const pool = new Pool({ max: 10 });
```
### Reference
- PostgreSQL docs: https://www.postgresql.org/docs/current/runtime-config-connection.html
Weak example
## Database
Databases are important.
You should optimize them.
That is all.
Quality checklist before PR
- Every heading adds new information and avoids repetition.
- Claims are testable, precise, and not outdated.
- Code or command snippets are runnable and relevant.
- Typos, grammar issues, and broken links are fixed.
Metadata-only improvements are also valuable.
+10
points are awarded for fix-metadata improvements after merge.
