[style, styling, guideline, contribute, writing]


Style Guidelines

Adopt Our Style of Communication

We are glossy and nerdy. We are welcoming, competent and helpful. We seek to cheerfully inform our users. We communicate concisely.

Will you blend in?

Language

Please develop your content in English.

Start Your Content With Our Templates

Please use our templates when developing new building blocks or tutorials.

Style Your Content

Your content is written in Markdown, and is automatically rendered in our house style.

You can also make use of code highlighting and admonitions.

Code Highlighting

In addition to the standard way of formatting code in Markdown, code snippets can be displayed in special boxes that highlight the code based on the programming language.

Provide your code in all the relevant languages and/or operating systems and specify them after the three back ticks. Wrap all of your snippets (in different languages) inside a codeblock shortcode (see our templates for more info on this).

# some Python code here
print("Hello, world!")
# some R code here
cat('Hello, world!')

LaTeX Integration & Math Formulas

You can include mathematical notation via our KaTeX integration. You can learn more on how to use it here.

If you use KaTeX more than once within the same Markdown file, there’s no need to write the shortcode again. Simply place your math formulas:

  • within single dollar signs for inline math: $f(x)=x^2$ yields: \(f(x)=x^2\)
  • within double dollar signs for display: $$f(x)=x^2$$ yields: $$f(x)=x^2$$

Highlighting Boxes

We support four kind of highlighting boxes.

Tip

This is a tip

Warning

This is a warning

Summary

This is a summary

Example

This is an example

Writing Instructions

  • Use the second person (“you”) when speaking to our or talking about our users
  • Content creators may refer to themselves in the first person (“I” in single-author articles, or “we” in multiple-author articles). Do remember to keep the focus on our users.
  • Avoid personal references: e.g., in my career, on a project I run.
  • We encourage the use of contractions: e.g., it’s, you’ll, you’re, we’re, let’s.
  • We prefer shorter words over longer alternatives.
    • e.g., “helps” is better than “facilitates”
    • e.g., “uses” is better than “utilizes”
  • Use an active voice wherever possible.
  • Write conversationally: prepositions are okay to end sentences with. And another thing. You can even start sentences with “And” or “But.”
  • Be informal, but being clear is more important than being entertaining!
  • Get to the point fast.
  • Frame sentences positively: use positive language (e.g., be more efficient, write better code…), rather than negative language (e.g., avoid mistakes…).
  • Avoid slang.
  • Avoid jargon. We know it’s difficult for you academics out there.
  • Capitalize Your Headings Like This. But don’t do that for articles and prepositions.
  • Avoid headings to start with articles and “How to…”. Of course we’re telling you how to do it.
  • Use ##, ###, #### for headers, not a standard line on bold. Use ** only for bolded words or short sentences when you want to stress a concept. Learn more about markdown syntax here.
  • Do NOT use # for headers. Instead, use the appropriate title flag for your main header.
  • Suggest at least one short link for your article! Combine an action verb and a noun like this: /VERB/NOUN (/do/this, /learn/that, /get/me). Ex. https://tilburgsciencehub.com/get/python. You will find these instructions in the contribution template.
  • Be consistent and double-check your file before sending!
Tip

If you want to be credited for your work, don’t forget to fill in the author and authorlink fields at the top of our templates with your name and a link to your personal webpage, respectively.

Warning

The naming of your file matters!

We use the filename, which is different from the actual article’s title, to extract information and display the current path within the navigation menu and on the breadcrumb trails. Please, choose your filename carefully!

Generally speaking, it’s a good idea to name your file exactly like your main title, but using all lowercase letters and separating words with a -.

Example:

Title: Automation with GNU Make
Filename: automation-with-gnu-make.md

Develop content for our target audience

When contributing content to our platform, please address at least one of our target groups.

  1. Students and novice researchers who look for material developed, curated, and rigorously tested by professors and experienced users, ensuring them about quality and usability. Users may not know yet what (and why) they should learn the Tilburg Science Hub way of working. These users need to be onboarded first and guided through our content.

  2. (Advanced) researchers and professors who look for useful material developed by their peers. These users have identified a problem, but need code snippets to use in their projects. Researchers seek to avoid mistakes that others have made before them, and look to get inspired by their colleagues. They may also use our platform to share their solutions to problems (e.g., in the form of building blocks or tutorials).

  3. Teams and small businesses who wish to get inspired by how scientists work on on data-intensive projects. Tilburg Science Hub offers tools and knowledge to help teams work together better, more efficiently. Our content can be adopted by individual team members (i.e., adoption doesn’t disturb the way of working of other team members), or jointly by a team (i.e., the entire team commits to the Tilburg Science Hub way of working).

  4. Data science enthusiasts who encounter our site when working on their projects. We strive to become a key learning resource in the data science community.

Warning

Keep in mind our key goals

Our platform focuses on usability (i.e., ability to quickly copy-paste code or download templates), speed (i.e., loading time), and attractiveness (i.e., visual appeal, “state-of-the-art” look, good writing).

Our platform is a (classical) two-sided market.

  1. We attract novice and expert users that use our content in their work, and

  2. We build a community of content creators that have an outspoken vision on how to conduct science efficiently.

Warning

License

Text and content are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. In other words, our content can be reused by anybody for non-commercial purposes, but needs to be properly cited.

Creative Commons Licence