This is a description of how I write tech articles for various blogs. Hopefully someone else will find this useful as well.
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.
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.
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.
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.
- Create a secret Gist for the article.
- Select a file format to write the article in.
- GitHub can automatically render some formats, which makes reading the Gist on the web page easier.
- If you have any collaborators, use a format all the collaborators are happy to edit.
- 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.
- Use Pandoc to render the article in a publishable format.
- If the Gist contains code examples, include a link back to the Gist.