Writing Guidelines

Help us keep OopsIT a valuable resource by following these guidelines when writing tutorials.

What Makes a Great Tutorial

The best OopsIT posts are honest, practical, and teach through real-world experience. They explain not just what to do, but why something went wrong and how you figured it out.

Structure

A well-structured tutorial typically includes:

A clear, descriptive title that tells readers what they'll learn
Context about the problem or scenario
Step-by-step instructions with code blocks
Explanation of what went wrong and why
The solution and how to verify it works
Key takeaways or lessons learned

Do

Write from personal experience
Include actual error messages and logs
Use code blocks with syntax highlighting
Specify OS, versions, and environment details
Link to official docs for further reading
Add tags to help others find your post

Don't

Copy-paste from other sources without attribution
Write vague, untested instructions
Include sensitive data (passwords, API keys, IPs)
Post promotional or spam content
Be dismissive or condescending to readers

Pro Tips

Start with the “oops” moment — what went wrong makes for a compelling hook
Use screenshots for UI-related tutorials
Include a TL;DR at the top for experienced readers
End with “What I learned” to add reflection and value

Markdown Support

OopsIT supports standard Markdown formatting including headings, bold, italic, code blocks, lists, links, images, blockquotes, and tables. Use the toolbar in the editor for quick formatting.