Tag Archives: writing

25 Mar
2024

Reviewdog filter settings with GitHub Actions

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI. I use it with Vale, and it’s really good. One thing that has tripped me up multiple times is that by default, it only applies the checks to the changes in the pull request, not to the whole project. So when you add something like Vale, which is a prose linter, it only checks … the workflow file you just added! I always forget that it works this way, and how to change it, so I’m pasting some examples for future reference. Continue reading →
03 Jan
2023

Generating a nice-looking PDF with Pandoc

Pandoc is one of my favourite tools in the world. If you haven’t come across it before, it converts between more or less any two document formats. I use it a lot with MarkDown and ReStructuredText so that I can produce content efficiently and then share it in a way that looks nice, but also to get word documents into cleaner formats. However the PDF output has always looked a little bit … dated? (this is rich from an rst2pdf maintainer I know!) and I was recently delighted to find some tricks that resulted in a better PDF. I’m sharing them here, so I can find them again in the future; you are welcome to use them too, of course! Continue reading →
11 Apr
2022

Outline your writing to ease the creative process

For most of my career I’ve been a software developer, but now I’m mostly a communicator. As a manager, I give the right level of detail to many different audiences, and I deliver that in words they can understand. As a Developer Advocate, I explain complex technical concepts in useful, memorable, and occasionally entertaining ways. However the best software developers are lazy and I’m still always looking for ways to get things done with less effort on my part! For writing, the best process I know feels like unnecessary overhead, but it’s always worth it in the end so today I’m sharing my secrets: create an outline before you start. Continue reading →
06 Dec
2018

Are you Creating, Curating or Consuming?

I’ve been thinking lately about my own interactions online, especially around content. There are three main ways that I work with content: creating, curating and consuming. Each has their own place but I’ll start by outlining each one.

Creating content is all about putting your own creations out for others to share. I’ve had this blog longer than I care to discuss and certainly since before microblogging was really a thing. It’s much lower investment to throw out a quick tweet about something and in lots of cases it’s a more appropriate medium Continue reading →

21 Jan
2015

Gollum the Git-Enabled Wiki

In trying to get company documentation off google docs and people’s laptops and into a more useful format, I have been researching developer-friendly tools for business documentation. Requirements went something like:
– must handle words and documents
– should be available locally, bonus points for revision history
– must publish to the web, and ideally be editable there
– should accept content in markdown
– must have access control (which wiped out my original plan of using a static site generator)

While I worked on this, we were using the wiki feature in GitLab … which pretty much hit the nail on the head. Further investigation showed that the wiki feature in GitLab (and indeed in GitHub) is a ruby gem called Gollum. Continue reading →

21 Oct
2014

Announcing the Git Workbook

I’m very pleasedtitle_page to announce the immediate availability of my new book Git Workbook, costing $20 from LeanPub. This is a book that you “do” rather than “read”; it’s a series of chapters (30 ish so far) each covering one specific git skill.

Each chapter includes an explanation of the skill in question, followed by a hands-on exercise so that you can work through the skill yourself, and ends with a tickbox so you can keep track of how far through you are. It has quizzes, diagrams, mildly amusing stories, and as many other examples as I could think of that could help anyone to take in this technical topic and understand how to apply the techniques covered. Continue reading →

10 Sep
2013

Generating HTML from Markdown with Pandoc

I’m writing more and more things that are not code these days, and my content-managing toolchains are becoming more developed all the time. I’ve written in REstructured Text, Asciidoc, and LaTeX, and today I’m working on an article which eventually wants to be HTML but I’m creating in Markdown because it’s much easier.

My swiss army knife of document formats is a program called pandoc. It’s absolutely fabulous, powerful, and not too complicated if you don’t need to do anything too complicated. It will guess input and output formats from file extensions, or you can be more specific if you need to. Today’s command looks like this:

pandoc article.md -o article.html

You won’t be surprised to hear that this command takes a file called article.md which contains my markdown, and outputs a file called article.html containing the HTML. I also use this to convert between all the various text markups, HTML, but also PDF and office document formats – it’s a very comprehensive tool!

25 Feb
2013

How To Write 800 Blog Posts

This is the 800th published post on lornajane.net. It’s my personal blog and I started it in early 2006, when I moved to a new city with no job. I think I got the blogging bug just because I had nobody else to talk to at the time! Over the years the blog has recorded recipes, craft projects, the story of buying and refurbishing the house (a decision that a previous employer described as “brave”) – and of course the vast swathes of technical snippets that are the regular content you see here.
Continue reading →