Contributing to the Netlify Developer Hub

The Netlify Developer Hub is a place to find articles and guides on how to build web experiences that thrive in our ecosystem. This not only includes information on how to use Netlify features and capabilities, but also features content on how to use tools and services around the ecosystem as part of a composable architecture. Your feedback and contributions can make it better for everyone, and there several ways you can get involved.

#TL;DR

Giving feedback and contributing to this site is possible with varying degrees of effort required. Ranging from a couple of clicks, to going all-out to author content. We’ll describe those, and also give more detailed guidance how to structure content contributions.

#Ways to contribute

We’re excited to create guides and and provide information to assist developers building with popular tools, frameworks, and services in order to help them achieve their goals with Netlify. You can join that effort in a number of ways:

1. Give feedback on an existing guide
2. Suggest an idea for a new guide
3. Write a guide

#1. Give feedback on an existing guide

You might want more of the same. You might wish the a guide had more detail about a certain thing. Perhaps there are ways that some concepts were explained or demonstrated in a guide that you found difficult to understand, or really suited you preferred method of learning.

Whatever your thoughts, we’re eager to hear them so that we can continue to improve the guides, and make them more useful for more people.

You’ll find a feedback form at the end of every guide. (Including this one. Look look, it’s down there.)

We’re listening, and grateful for your thoughts.

#2. Suggest an idea for a new guide

We have a lot more guides and information planned for this site, but you can influence our content plan. Let us know if there are themes or topics that you’d like to see an article about.

Your suggestions can really help us prioritize what people are keen to learn about, and may even influence the way some features and capabilities surface in Netlify itself. Want to know how to do something on Netlify? Let us know!

A form where you can submit ideas and suggestions for new guides can be found on the Guides page. Let us know, and we’ll see what we can do!

#3. Write a guide

We also accept contributions to the Guides section of this site. If you’re keen to contribute an article to help developers achieve one of their goals, then we’re happy to consider it.

Contributing a guide is done by arrangement with the team here, so before you crack those knuckles, write thousands of words, and send it our way, let’s chat!

Reaching out via the Suggest a guide form is a good place to start. We can talk you through the process and help to get your article published and promoted right here on the Netlify Developer Hub.

#Guidance for writing a guide

The following guidance is intended to help those on the process of writing a guide for inclusion here on the Netlify Developer Hub. We have a few conventions and patterns we like to embrace.

#Structure

We like our guides to include these sections in order to have some consistency and feel familiar and useful to readers:

1. Title
2. Introductory paragraph
3. A quick TL;DR
4. The place where the magic happens
5. More resources and next steps

#1. Title

Did any anyone ever mention that naming things is hard? It can be! Making your title clear, descriptive and action-oriented is good. As is keeping it concise.

#2. Introductory paragraph

Now is the time to let the reader know that they’re in the right place, and that this is an article that can help them. Most of us have short attention spans, so we present this as a single paragraph. (As you can see above).

The intro sets up some context for what you’ll be diving into, describes to the reader why they might care about this topic, and mentions any of the foundations that wil be useful to help them understand that this article is just what they were looking for. I tried to do that in the intro paragraph to this article.

#3. A quick TL;DR

Once you’ve given some context and suggested why somebody might want to read this guide in your intro, it’s time to give a quick summary of what the article will contain.

As developers, we’ve become familiar with the concept of a tl;dr (Too long; didn’t read) as a way to summarize a more detailed message or article. We use that here as a little convention to tell the reader what to expect nice and early.

We did it earlier on this page too, remember?. Hopefully you’ve kept reading because this section told you what to expect, and it aligns with what you needed

#4. The place where the magic happens

Now it’s time for the core content of your guide.

A detailed guide and reference examples that developers can follow to achieve their goals, as indicated in the Intro and TL;DR sections is what we’re after here.

Code snippets, links to examples and demonstrations, and explanations that help to build an understanding for the reader belong here.

We find that code repos containing examples and demonstrations that developers and clone and deploy are particularly impactful, and encourage you to include those where appropriate.

#5. More resources and next steps

To wrap things up, it’s good to provide some links to more information, deeper reading, or next steps. Recapping links to any examples or demos included cab also be useful here.

#Helper components for our guides

We have a number of components available to use in Guides for convenience and visual consistency.

#Callouts

Available in two types: tips and warning with tips being the default if you don’t specify a type. Both can wrap markdown or HTML.

<Callout title="A useful note" type="tip">
  Content to draw some particular attention too
</Callout>

<Callout title="An important warning" type="warning">
  Danger, Will Robinson
</Callout>

#Video

It can be useful to include videos to demonstrate or describe some things. We make use of Paul Irish’s lite YouTube embed utility and have a little helper to let us add a higher-resolution custom poster image.

<Video id="YOUTUBE_VIDEO_ID" poster="PATH_TO_CUSTOM_POSTER_IMAGE" />

#Deploy To Netlify Button

An added layer of convenience for rendering a Deploy to Netlify Button by providing just the URL of the code repository of the example to clone and deploy

<DTNButton repo="https://github.com/netlify/netlify-feature-tour" />

#What next?

If you’re interested in publishing a guide to building for the web here on the Netlify, we’d be happy to hear from you. Likewise if you have suggestions for guides or feedback on what you’ve found here on the Netlify Developer Hub.

• The Suggest A Guide form
• You can chat with us on social media about potential guides and things you’d like to learn