My Workflow

한국어 버전은 여기에서 읽을 수 있습니다.

I will explain how I write and what tools I use to write articles and program codes. This workflow is not de facto nor everyone likes. But it might be good to a few persons as reference. If you have a way better than this or any good advise, please share on the below disqus.

Writing

Usually I write to do below things:

1. To write my homepage posts like what I’m currently doing.

2. To do documenting internal docs such as writing manuals that I design or writing issue reports.

I have two different approaches.

Writing posts to this website

I’ve used Hakyll to generate my site contents. My site contents are pure static, which means there are no databases nor PHP, Python, Ruby to produce any pages. You might be heard of blogging tools such as Wordpress or Joomla. These tools are running always in background on the server to handle visitors’s requests. So, server has to run PHP-CGI or Python-WSGI in addition to HTTP daemon.

Running such tools consume server resources (process or memory). The amount of resource is not too big in order to run small-sized site like this site. But low-grade server takes longer time to do that if site is crowded.

Static website just serves static contents such as htmls, javascripts, css stylesheets, and images. It doesn’t use any PHP, Python, nor Ruby scripts. It means server just hands over internal files to visitors. Processing time is quite instant. This means server can handle more requests at the same time.

As I explained above, I generate my site contents. I do it offlined. Then I just put the site contents to server directory. So I write posts not on the web browser nor on server but in my laptop offlined.

Site’s html contents can be written as raw. But writing in html is quite hard-working job. For example, site design scheme should be written to every single page. Then actual contents should be put among messy html tags. To avoid this hell, I’ve use html generator tool. There are well-known generator tools such as Jekyll, Flask, and much more. I’m using Hakyll which is written in Haskell, functional programming language.

Hakyll uses Pandoc library to generate html contents. Pandoc supports various text formats (Markdown, reStructuredText, html, literate haskell, or latex) as input source. I use Markdown as written format. Markdown is clean and well formed even as raw text.

The tool I’ve used to write is Vim that many people don’t like. I’ve used Vim as Markdown editor for the below reasons:

1. Vim can be run on Unix, Windows, and Mac OS. It can be shown as same on any machine even on console.

2. Complicated features are not required to write just Markdown posts. Insertion, deletion, copying, pasting, and a few hot-keys are enough to begin writing.

3. Vim supports many syntax highlightings. It also supports markdown. That syntax highlighting is quite clean and dense.

I’d used other tools. But everything else was not fittable to me. WriteMonkey support markdown format. But it has problem on Korean input system. To solve the issue, syntax highlighting should be turned off. It makes me a lot worse readable than Vim’s. Scrivener has plenty of features. So, I could organize any subject-related informations effectively. But Scrivener’s saved contents are its own binary format. So I was not able to manage those files in version control system(VCS).

Vim configuration

Vim supports fullscreen mode in Mac if you use MacVim. Fullscreen mode is not possible in Windows or Linux. With this mode, vim shows somewhat like Day One app.

function! DistractionFree()
    if has('macunix')
        NERDTreeClose
        set fuoptions-=maxhorz
        set columns=82
        set laststatus=0
        set fullscreen
    endif
endfunction

I use NERDTree plugin in vim. Thus, close it then align to center. Then set columns as 82 then switch to fullscreen mode.

Update (2016-12-28) Recently, I’ve used Atom along with Vim. Atom supports lots of theme (syntax highligting too) and many packages such as minimap imitating Sublime Text sidebar. Although it consumes relatively lots of memory but I will keep using Atom as main Editor thanks to above advantages. / End of Update

Version Control

Markdown files (.md) are saved into Git repository. So I can have version control system(VCS) advantages. The Git repository is cloned to server repository and bitbucket both. This git repo contains markdown docs and design templates. The Hakyll configuration code is publicly accessible at Github. Images, however, take large storage space, so I didn’t put images into the repository. Temporary, I sync them with Google drive but I need to find better solution.

After writing is completed, I push the patch to git repo in server. Then server builds site contents automatically. Git post-receive hook script compiles configuration, run the compiled code, and generate htmls after receiving commits.

Update (2016-12-28) After moving the site into AWS S3 bucket, I no longer use ‘post-receive hook’ since no 24/7 running server is available. Maybe Travis CI, Circle CI can be used but at this moment I build the site on my laptop. / End of Update

Writing for internal docs

Internal docs that I talk about is the documents I do not upload to site. They might be issue reports, hardware design manuals, work manuals.

Emphasizing documenting is no upper bound. Well-written documents help other people follow-up your work. You can also recite with the docs. So I’ve written docs as mush as possible while working. To be convinient, I use text editor not word processor.

I somewhat prefer raw text to other text formats. I might have anxiety about saving into subordinate formats. But there are a few merits to save as raw text.

1. Raw text occupies small amount of storage. Usual Word file (.docx) consumes much more space even though actual text is quite small. One letter consumes one to three bytes. Usual docs just consume at most a few hundreds kilo bytes. In addition, the word program is quite heavy. It requires good hardware spec.

2. VCS can be used. I use Git as Version Control tool. Git is specialized to raw text managment. If the file is binary format, Git saves entire file as new. Git saves just difference between old text and new one if it is raw text.

3. The docs can be published easily. They look good as raw text. But I prefer publishing as PDF to sharing as raw text.

Documenting in raw text has good ones and also inconveniences. One of the inconveniences is writing tables. Simple table is easy to write as raw text, but it is really annoying me if the table size is more than small. I couldn’t find good solution for this issue. I considered converting excel into text, but the result was not good. So, I’m getting reducing tables in the documents.

Pandoc can generate PDF format from Markdown format. But I step one more between markdown and pdf. I convert markdown to latex first, then substitute verbatim environment to FancyVrb (Verbatim environment). Then I convert latex to PDF with pdflatex tool.

You can find the configuration in Docs repo.