jkpl/writing_tech_articles.md

## writing_tech_articles.md

      
    Raw
  

              writing_tech_articles.md
            
          
    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.

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.


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.