Blog Writing Style Guide

This document describes the writing style for blog posts based on analysis of existing posts. Use this guide when writing new blog content or when AI assistants help with blog writing.

Core Writing Principles

Voice and Tone

  • First person perspective: Use “I” freely when sharing personal experiences, opinions, and workflows
  • Conversational but professional: Write as if explaining to a colleague over coffee
  • Direct and practical: Get to the point quickly without excessive preamble
  • Honest and reflective: Share genuine experiences, including uncertainties and limitations
  • Encouraging: Supportive tone when giving advice, especially to early career researchers
  • Accessible to non-specialists: When writing for general audiences, use analogies and plain language

Sentence Structure

  • Active voice preferred: “I attended a symposium” not “A symposium was attended”
  • Short to medium sentences: Aim for clarity over complexity
  • Varied sentence length: Mix shorter punchy sentences with longer explanatory ones
  • Contractions acceptable: “I’m”, “don’t”, “it’s” are fine and add conversational tone
  • Rhetorical questions: Use sparingly to engage readers: “Would you consider yourself to be a science communicator?”

Language Choices

  • Plain language: Avoid unnecessary jargon; explain technical terms when needed
  • Concrete over abstract: Use specific examples rather than vague generalizations
  • Minimal qualifiers: Avoid overuse of “critical”, “key”, “essential” - just state things directly
  • Technical precision where needed: Use correct terminology for R packages, software, and methods
  • Vivid analogies: Use relatable comparisons to explain complex concepts: “Mosaics of habitats are like shops around a village town square”

Blog Post Types and Their Styles

1. Tutorial/How-To Posts

Examples: “Writing scientific papers with quarto”, “Bayesian structural equation model tutorial”, “Automating the Github Copilot Agent”, “How to use large language models to assist in systematic literature reviews”

Structure: - Brief introduction explaining what the tutorial covers and why it’s useful - Clear numbered or bulleted steps - Code examples in fenced code blocks with minimal commentary - Links to external resources for deeper dives - Practical warnings about common pitfalls

Style characteristics: - Imperative mood for instructions: “Download and install VScode” - Present tense for describing processes - Personal asides acceptable: “I, of course, want to do everything from the R program” - Honest about limitations: “This is the hard part that needs a lot of thought” - Include your actual workflow: “Here’s my current set-up”

Opening pattern: - State what the post covers - Give 2-4 reasons why this approach is useful - Acknowledge downsides or challenges upfront

2. Advice/Research Skills Posts

Examples: “How to work with non-governmental organisations”, “Chris’ secret recipe to writing papers quickly”

Structure: - Brief context-setting introduction (1-3 paragraphs) - Numbered list of key lessons or tips - Each point includes explanation and practical examples - Personal anecdotes to illustrate points - Concluding reflection on broader significance

Style characteristics: - Bold headings for main points - Mix of prescriptive advice and explanatory context - Personal experience as evidence: “Working with NGOs has been one of the most rewarding parts of my career” - Practical caveats: “Just be mindful that…” - Realistic about challenges and trade-offs

Tone: Mentoring and supportive, sharing hard-won wisdom

3. Reflective/Data-Driven Posts

Examples: “How long does it take to write major national grant?”

Structure: - Question or observation as hook - Personal data or experience - Analysis with specific numbers - Multiple perspectives on the data - Caveats and limitations - Invitation for reader input

Style characteristics: - Specific quantitative details: “69 hours and 30 minutes” - Transparent about methodology and limitations - Multiple interpretations considered - Conversational asides: “the answer surprised me” - Analogies to make numbers relatable: “Consider that it takes ~33 hours of climbing to ascend Everest”

Tone: Curious and analytical, inviting discussion

4. Research Communication/Science Outreach Posts

Examples: “Saving ocean animals means restoring multiple habitats”, “Giant kelp restoration could boost fisheries productivity”, “Ambitious conservation action sees a brighter future”

Structure: - Engaging opening with accessible hook - Clear explanation of the research problem - Description of methods in plain language - Key findings with visual support - Broader implications and future directions - Links to papers and further reading

Style characteristics: - Accessible language for non-specialist audiences - Vivid imagery and analogies: “underwater grass”, “like shops around a village town square” - Present tense for describing what is known - Past tense for describing the specific study - Image captions that explain and credit - Balance between simplifying and maintaining accuracy - Personal involvement: “When Michael invited me to help with the data analysis I jumped at the chance”

Tone: Enthusiastic about the science, educational, accessible

5. Problem-Solving/Debugging Posts

Examples: “A case against pipes in R”, “Smoothing a time-series with a Bayesian model”

Structure: - Identify the problem or challenge - Explain why it matters with concrete examples - Show the issue with code examples - Present solutions with working code - Discuss trade-offs and limitations - Optional: acknowledge community feedback and alternative solutions

Style characteristics: - Honest about mistakes and bugs: “These are always the types of bugs that don’t throw an error” - Working code examples that demonstrate the problem - Step-by-step solutions - Acknowledgment of learning process: “I’m starting to see a pattern” - Updates based on feedback: “(This part is new as of 2020-04-22)” - Pragmatic advice: “So I plan on keeping up pipes, but just for simple things”

Tone: Helpful problem-solver sharing hard-won lessons

6. Reflective/Personal Narrative Posts

Examples: “How I became a science communicator without realizing it”

Structure: - Opening question or theme - Chronological or thematic narrative - Personal anecdotes with specific details - Lessons learned or insights gained - Closing reflection or call to action

Style characteristics: - Story-telling approach with personal details - Quotes from others (teachers, colleagues, critics) - Honest about failures: “I felt that if this was what scicomm was about, it definitely wasn’t for me” - Evolution of thinking over time - Specific moments that changed perspective - Acknowledgment of supportive people and institutions

Tone: Reflective, personal, encouraging

7. Advice/Framing Posts

Examples: “Points to consider when framing a regional study for the international literature”, “Should I post my manuscript to a pre-print server?”

Structure: - Clear question or challenge stated upfront - Organized points (numbered or bulleted) - Each point explained with rationale and examples - Pros and cons when relevant - Practical guidance - Personal experience or lab discussion context

Style characteristics: - Structured with clear headings and subheadings - Bullet points for pros/cons lists - Strategic thinking: “Frame your findings in terms of broader ecological patterns” - Acknowledgment of contributors: “Thanks to Jordan Holdorf for helping me write this post” - Balanced perspective: “Overall, the benefits usually outweigh the drawbacks” - Specific actionable advice

Tone: Mentoring, strategic, balanced

8. List Posts

Examples: “Chris’ secret recipe to writing papers quickly”

Structure: - Minimal introduction - Numbered list (sometimes with sub-points) - Brief explanations for each item - Minimal conclusion or none at all

Style characteristics: - Terse, direct statements - Occasional parenthetical asides: “(three or less or have none)” - Practical wisdom distilled to essentials - Some items may reference other items: “see points 1 and 2” - Acceptable to have informal numbering: “3. (b) Sub-point”

Tone: Experienced practitioner sharing shortcuts

9. Announcement/Course Posts

Examples: “Beginner Intermediate and Advanced R courses February 2019”

Structure: - Clear announcement of what’s being offered - Practical details (dates, location, registration) - Course content outlined - Testimonials if available - Contact information

Style characteristics: - Straightforward and informative - Bulleted lists for course content - Specific details: dates, locations, instructors - Quotes from past participants - Clear calls to action with links

Tone: Professional, informative, promotional but not pushy

10. Press Release/Research Announcement Posts

Examples: “Ambitious conservation action sees a brighter future for mangroves and seagrass”

Structure: - Lead paragraph with main finding - Quotes from researchers - Context and significance - Methods briefly mentioned - Broader implications - Links to published paper

Style characteristics: - Third person when quoting yourself or colleagues - Formal but accessible language - Quotes formatted as block quotes or inline - Attribution of quotes: “said Dr Christina Buelow” - Emphasis on significance and impact - Link to published research

Tone: Professional, authoritative, optimistic about findings

Formatting Conventions

Headings

  • Use sentence case for titles: “How to work with non-governmental organisations”
  • Numbered headings for tutorials: “### 1. Download and install an IDE”
  • Question format acceptable: “How long does it take to write for major national grants?”

Lists

  • Numbered lists for sequential steps or ranked items
  • Bulleted lists for non-sequential items or features
  • Bold the first phrase of list items for emphasis when appropriate
  • Keep list items parallel in structure

Code and Technical Content

  • Use inline code formatting for: package names, function(), file.extensions, command-line tools
  • Use fenced code blocks for multi-line code examples
  • Minimal code comments - let the surrounding text explain
  • Show actual working examples from your projects

Emphasis

  • Bold for key terms, list headings, and important warnings
  • Italics used sparingly, mainly for emphasis in specific phrases
  • ALL CAPS rarely used, mainly in technical contexts like YAML

Opening Strategies

Strong Openings

  1. Personal anecdote: “I attended a symposium for scientists and non-governmental organisations…”
  2. Direct statement of purpose: “Below is my suggested workflow for using quarto…”
  3. Question hook: “How long does it take to write for major national grants?”
  4. Context + announcement: “[Tool] recently became available. It is an AI agent…”

What to Avoid

  • Don’t start with dictionary definitions
  • Don’t use “In this blog post I will…” (just do it)
  • Avoid excessive throat-clearing before getting to content

Closing Strategies

Effective Endings

  1. Personal reflection: “Working with NGOs has been one of the most rewarding parts of my career”
  2. Invitation for input: “I will be interested to hear how much time other people spend on grants”
  3. Practical caveat or warning: “Note that if you are using the .bib directly just be careful not to plagiarise!”
  4. No formal conclusion - just end when the content is complete (especially for tutorials)

What to Avoid

  • Don’t summarize what was just said
  • Don’t use formulaic “In conclusion…”
  • Don’t end with vague calls to action

Content Characteristics

Personal Elements

  • Share your actual workflows and setups
  • Admit limitations: “I’m not great with unix code or Python”
  • Include learning journey: “something I’m still developing…”
  • Reference your own papers and projects
  • Mention specific tools and versions you use

Practical Focus

  • Prioritize actionable advice over theory
  • Include specific examples and numbers
  • Acknowledge trade-offs and downsides
  • Provide links to resources for deeper learning
  • Share actual code, commands, and configurations

Honesty and Nuance

  • State caveats clearly: “A few caveats on my estimate”
  • Acknowledge uncertainty: “I’m guessing the tools are…”
  • Note when something is difficult: “can be tricky to connect VScode to R”
  • Admit when you don’t have all answers: “I’m working on a template, but am not yet ready to share it”

Common Phrases and Patterns

Transitional Phrases

  • “So here are the key lessons”
  • “Here’s an example in action”
  • “A few key points”
  • “Now we’ll step through…”
  • “Instructions below are high level”

Qualifying Statements

  • “Just be mindful that…”
  • “That being said…”
  • “This is the hard part…”
  • “There is still some risk here”
  • “Its worth also learning…”

Explanatory Patterns

  • “The reason X is that Y”
  • “This means you could…”
  • “The advantage of X is Y”
  • “For instance…”
  • “e.g.” and “i.e.” used naturally
  • “In other words…”
  • “To put it another way…”
  • “What this means is…”

Acknowledging Others

  • “Thanks to [name] for helping me write this post”
  • “Thanks to the [lab/group] for their contributions”
  • “My colleague, [name], worked with…”
  • “When [name] invited me to…”
  • Credit photos and images: “Photo by Chris Brown”

Technical Writing Specifics

R and Programming Content

  • Package names in code format: lavaan, piecewiseSEM
  • Function calls with parentheses: system()
  • Show complete working examples
  • Explain security considerations when relevant
  • Link to official documentation

Academic/Research Content

  • Reference your own papers naturally
  • Cite specific examples from your work
  • Include links to GitHub repos and data
  • Mention collaborators and institutions
  • Provide context for research decisions
  • Link to published papers with DOIs
  • Offer free access versions: “Free access version here”
  • Provide email for paper requests: “email me for a copy”

Images and Figures

  • Use descriptive captions with context
  • Credit photographers: “Photo by Chris Brown”
  • Explain what images show: “Image: Boundaries of different habitats…”
  • Reference figures from papers when relevant
  • Use images to break up text and illustrate concepts
  • Alt text for accessibility (in HTML contexts)

Metadata and Front Matter

Categories Used

  • research-skills - advice for researchers
  • rstats - R programming content
  • genAI - generative AI topics
  • research - general research topics
  • coastal-wetlands - coastal ecosystem research
  • Multiple categories acceptable: [rstats, genAI, research-skills]

Title Patterns

  • Descriptive and specific
  • Often start with “How to…” for tutorials
  • Questions for reflective posts
  • Gerunds acceptable: “Writing scientific papers with quarto”

Voice Consistency Checklist

When writing or editing a blog post, check:

Examples of Style in Action

Good: Direct and Personal

“I, of course, want to do everything from the R program, because I’m not great with unix code or Python.”

Good: Honest Caveat

“Now I wouldn’t recommend using --allow-all-tools like this however. There are important security considerations.”

Good: Practical Specificity

“So aim for projects that need 6 months to a year to complete. Talk to your supervisor about projecting time needed, as we all tend to underestimate that.”

Good: Conversational Transition

“Here’s an example in action. I use sprintf to format the terminal command with the prompt, tools and sub-directory path.”

Avoid: Overly Formal

“It is imperative that one considers the security implications prior to implementation.”

Avoid: Vague Generalization

“This is a critical tool that provides key functionality for essential workflows.”

Good: Accessible Analogy

“Mosaics of habitats are like shops around a village town square. A village with just lolly shops would suit my children, but not many others.”

Good: Acknowledging Limitations

“The models focused on overall ecosystem productivity gains, but giant kelp provides additional benefits not captured in these predictions.”

Good: Personal Narrative

“I never got very good marks in writing, but my creative writing teacher (Karen Clark) said something that has stuck in my head all these years.”

Good: Problem Identification

“Most of the really insidious bugs occur in sections of code that use dplyr tools and pipes. These are always the types of bugs that don’t throw an error, so you get a result, it just turns out to be wrong.”

Special Considerations

Writing for Different Audiences

For scientists/technical readers: - Use technical terminology appropriately - Include code examples and mathematical notation - Reference specific packages, methods, and papers - Assume familiarity with basic concepts

For general/public audiences: - Use analogies and plain language - Explain technical terms when first used - Focus on implications and applications - Use vivid imagery: “underwater grass”, “fish wee and poo”

Handling Uncertainty and Limitations

  • Be explicit about what you don’t know: “I haven’t read how to choose the ‘optimal’ value”
  • Acknowledge when something is difficult: “This is the hard part that needs a lot of thought”
  • State caveats clearly: “A few caveats on my estimate”
  • Invite input: “Message me on Twitter if you have seen an example”
  • Update posts when you learn more: “(This part is new as of 2020-04-22)”

Community Engagement

  • Acknowledge feedback: “So once this post got shared I got a lot of feedback”
  • Credit people who helped: “Roger Bivand wrote to tell me about…”
  • Invite discussion: “I will be interested to hear how much time other people spend”
  • Provide contact methods: Twitter handles, email addresses
  • Share on social media strategically

Evolution and Updates

  • Add dated updates when new information emerges
  • Acknowledge when your thinking has changed
  • Reference previous posts when building on ideas
  • Show learning journey: “I’m starting to see a pattern”

Final Notes

This style guide captures patterns from existing posts. The style is flexible and adapts to content type, but maintains consistency in: - Directness and clarity - Personal voice and honesty - Practical focus - Conversational professionalism - Respect for reader’s time - Accessibility across audiences - Acknowledgment of collaborators and community

When in doubt, prioritize being helpful and clear over being impressive or comprehensive. Write as if you’re explaining to a colleague who wants to learn, not to impress reviewers.