Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Writing tech articles

Writing tech articles

This is a description of how I write tech articles for various blogs. Hopefully someone else will find this useful as well.

Create a Gist for the article

When I begin writing a new article, I create a new GitHub Gist for the article files. The Gist contains a file for the article text and code examples related to the article. Because the article is not finished yet, I mark the Gist secret, so that it's not publicly listed.

Once the Gist is created, I choose the file format for the article. I usually prefer writing the article text in GitHub flavored Markdown because it's well-known, but you can use pretty much any format you like. It's helpful to use a format that GitHub can render automatically.

Editing the article

Even though I'm using Gist for storing my article, I rarely use it's editor for more than quick edits. For larger edits, I usually clone the Gist repository on my local machine, and edit the files locally using a proper text editor (e.g. Emacs).

Like any other Git repository, Gists also preserve edit history. Therefore, I like to use semantic linefeed for my article text: dedicate a line for each sentence and clause to preserve nice editing history. Since the article text will eventually get rendered as HTML, the semantic linefeeds will get ironed out once the article is published.

All the code examples related to the article are included in the same Gist as the article. I usually also include build scripts (e.g. SBT file for Scala code), so that readers can just clone the Gist and run the examples with one command. Remember to place all of the files to the root of the Gist repository as Gist doesn't support directories. For more complex code examples that require directories, I recommend creating a separate Git repository.

Peer review and collaboration

I usually ask for people to review before I publish an article. I send the link to the article Gist to the people who've agreed to review the article. If you wrote your article in a format that GitHub can automatically render, the reviewer can easily read the article in the web page.

When I'm collaborating with other authors, I share the link to the Gist, and ask the other authors to fork the Gist. When the changes are being made available, I can then merge their changes to the original Gist locally using Git: I add the forks as remote branches to my local repository, merge the changes to my local master branch, and finally push the changes to the original Gist. It's also important to select a file format that all the collaborators are happy to edit.

Selecting a license

By selecting a license for the work, I can set the rules and conditions for how your work can be reshared.

I prefer using a license that gives people the freedom to share and adapt my work as long as I'm credited and that the adapted work also has the same or similar license. My favorite license is the CC BY-SA 4.0 license, which is one of the licenses in the Creative Commons family.

In the article that I'm writing, I either include a link to a page that explains the license used or include the license notice directly in the article.

Publishing

Once I'm happy with article I've produced, I render the article in a format I can publish it. The format pretty much depends on the platform, but most platforms I use accept HTML. Pandoc is a really good tool for converting text between formats.

If my article includes code examples, I make sure to include a link back to the Gist in the article, so that readers can easily find and download the full code examples.

Too long; didn't read

  • Create a secret Gist for the article.
  • Select a file format to write the article in.
  • Clone the Gist repository to your local machine, and edit the article with your own editor.
  • Use semantic linefeeds for cleaner editing history.
  • Include code examples in the Gist
    • Also include any build scripts that make it easier to run the code examples.
    • Directories are not allowed in Gists.
  • Share a link to the Gist with the people that can review your article.
  • Encourage collaborators to fork your Gist.
    • Changes can be merged to the main Gist by pulling from the forked Gists.
  • Select a license for your work if possible.
    • I highly recommend one of the Creative Commons licenses.
    • Make sure to include a license notice or a link to a license notice in your article.
  • Use Pandoc to render the article in a publishable format.
  • If the Gist contains code examples, include a link back to the Gist.
@seyijava
Copy link

seyijava commented Jul 6, 2018

kskfskfksfk

@ZhuangDingyi
Copy link

ZhuangDingyi commented Oct 30, 2018

Thanks for sharing. I am looking for a good place to share thoughts. lol

@cancerberoSgx
Copy link

cancerberoSgx commented Jul 7, 2019

I think it's a good idea to license the article if you care other to redistribute it unfairlyI'm this is similar to GPLL but for documentation. BTW I'm searching information about services that let me publish articles with my own license and seems noboty really care about tha... but just in case if you don't license you creation and accept github conditions I think you are giving others right to on it. Just a heads up

@jkpl
Copy link
Author

jkpl commented Jul 8, 2019

Thanks for the heads up! I do care about licensing, and it's definitely important to include that as part of the publishing process. I've kind of taken it for granted, which is probably why I didn't include a section about licensing. That's something I think I need to address here.

Personally, I've favoured Creative Commons for my content for a long time. Specifically, CC BY-SA 4.0. Do you know of any other similar content licenses that you'd recommend?

Stay tuned for an update!

@afaqahmedkhan
Copy link

afaqahmedkhan commented Aug 9, 2019

thanks! it helped!

@wenheqi
Copy link

wenheqi commented Dec 18, 2019

Thanks for sharing!

@khaterehsb
Copy link

khaterehsb commented Dec 30, 2019

really helpful! Thanks for sharing!

@timreichen
Copy link

timreichen commented Jun 8, 2020

Great Post. Thank you!

@caioh-ferreira
Copy link

caioh-ferreira commented Mar 22, 2021

Thanks for your post, bro. Just uploaded an article here. :)

@felix715
Copy link

felix715 commented Nov 10, 2021

Really its good guide..thanks for posting it.

@harsimran2084
Copy link

harsimran2084 commented Jun 12, 2022

@NicholasBarrett98
Copy link

NicholasBarrett98 commented Aug 27, 2022

I always wanted to be a successful writer. And I've been working on it for a long time. Sometimes when it was difficult to cope with writing assignments I asked for help. And when I was getting ready to go to university, I was helped by residency personal statement editing to write a persuasive personal statement for the committee. And I was accepted.

@anceent1952
Copy link

anceent1952 commented Sep 29, 2022

A fluid leak may be present if you notice a patch of fluid under your car as we previously explained let's look at the many types of liquids that leak from cars and how to spot them https://www.wesharescience.org/ Indeed even with the established principles and regulations governing homework we are not yet convinced if it could be helpful or not.

@mrnazu
Copy link

mrnazu commented Nov 28, 2022

thank you bros

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment