Initial Commit

Writer's Guide

How we write and publish articles here, from picking a topic to hitting publish.

This guide walks you through how we write and publish articles on Initial Commit: choosing a topic, outlining, drafting, visuals, formatting and publishing. Read it before you start writing. It saves a round of edits. If you haven't pitched us yet, start with Write for Us.

1. Choosing a topic

Every article on Initial Commit should be the best, most useful resource on the internet for its topic. Email us at jacob@initialcommit.io with what you'd like to write about and who it's for, or ask us for a topic and we'll suggest one readers are looking for.

Before you pitch a Git topic, check what we already have so you don't repeat it: the Git articles, the Animated Git Cheat Sheet and the Visual Git command reference. Every Git article also appears on one of our Git topic pages, so think about which one yours belongs on.

2. Your first article

Write your first article in a Google Doc and share it with jacob@initialcommit.io. If it goes well, we'll give you access to our admin portal for future articles, where you can write and submit them directly.

3. The SEO outline

For topics we suggest, we'll give you an SEO outline that describes what we're looking for: the angle of the article, the word count, the sections we expect, the keywords to use and any other useful details. Read it first, and ask us if anything is unclear.

4. Your author outline

Before you write the draft, send us your author outline. It should have:

  • The section headings you plan to use, with 2 or 3 bullet points on what each section will cover. The more detail, the better.
  • About 2 links to high-quality outside sources per 1,000 words.
  • About 2 links to other Initial Commit articles per 1,000 words.

We'll review it and let you know if anything needs to change before you start drafting.

5. Structure

Start with a short introduction. Then cover the topic in clear, digestible sections that follow the SEO outline. Section headings can use the outline's keywords where they fit naturally, and so can the body text. Don't overdo it, though. Stuffing keywords in where they don't belong hurts more than it helps. Then finish with:

  • Summary: a short recap of the main points.
  • Next steps: where to go from here. The post template fills in a starting point for this one.
  • References: a numbered list of the outside sources you used, with their links.

6. Style

  • Write in clear, fluent English with American spelling (color, not colour).
  • Keep it technical but easy for a beginner to follow. Explain terms the first time you use them.
  • Run every command and code sample yourself, and show the real output.
  • Write in your own words. Don't copy from other websites or documentation.
  • For a good example of what we're looking for, see this article.

7. Diagrams and images

  • Git diagrams: use git-sim to draw what a command does to a repository, so your article matches the look of the rest of the site. git-dummy can build a sample repository to draw it on. Include the commands you ran, so we can redraw the diagram if we need to.
  • Other images: screenshots and diagrams should be clear at a normal reading size. Only use images you made yourself or have the rights to use.
  • Cover image: each article has a 1920 x 1080 cover image named after its slug. We can make it for you.

8. Writing the draft

Once your outline is approved, write the draft:

  • Write it in Markdown.
  • Use H2 headings (## Heading) for sections. We use them to build the table of contents.
  • Write links as [text to link](https://www.url.com).
  • Put inline code in single backticks, like `git status`.
  • Put code blocks in triple backticks with the language, like ```python on the first line and ``` on the last.
  • Use as many of the SEO outline's recommendations as you can.

9. The admin portal

If you write more than one article for us, we'll create a login for you in the Initial Commit admin portal, where you can write and save your outlines and drafts. The portal logs you out after 10 minutes, so you may want to write elsewhere and paste your work in when you're ready to save it. When you create a new post, pick a post template, then fill in these fields:

  • Related post IDs: filled in for you.
  • SEO title and Title: both set to the title from the SEO outline.
  • Description: the meta description, as described in the SEO outline.
  • Categories: words separated by spaces. Git articles start with git vcs, filled in for you. Add one topic tag to put your article on its Git topic page: topic:basics, topic:branching, topic:history, topic:team, topic:rescue or topic:internals. Add cheat-sheet if it's a cheat sheet or quick guide.
  • Slug: the hyphenated page address from the SEO outline.
  • Slug alias: leave empty.
  • Image: the template fills in *.png. Replace the * with your slug.
  • Image (light): leave empty. We add a light mode version of the cover image if there is one.
  • Author: your name as you'd like it shown, filled in for you.
  • Create date and Last update date: today's date as YYYY-MM-DD, filled in for you.
  • Hide modal, Published, Featured and Hide sidebar: 0, filled in for you. We publish the article when it's ready.
  • Alt canonical, Sponsor header image, Sponsor header link, Post sponsor name and Post sponsor URL: leave empty.
  • Markdown: your outline, then your draft, in Markdown. The template fills in the section headings to start from.
  • Recommended product and Recommended course name and URL, and Cluster ID: filled in for you.

10. Review and publishing

When your draft is ready, let us know. We'll review it, send you any edits, and publish it once it's done. We take care of the final cover image and the publishing.

Have an idea for an article? Email us. We're also happy to suggest topics.