Writing tools I use. From Science Papers to Roleplay Games.
I’m going to explore a slightly different topic this month — writing. And not just blogging but the academic stuff I’ve been working on of late (and a couple of secret projects too!). I’m a bit of a beginner at this, but I’ve already discovered a number of tools and books that might be helpful for other folks in a similar position. I’m going to finish by posing a few questions and thinking about avenues to pursue going forward. Lets start at the beginning, with this blog!
Blogs and such.
I’ve been writing this blog for some-time now. I’ve used various approaches but at the moment, I’m using Vim for the most part, along with a custom program I cal tachikoma — essentially the same thing as Jekyll but written in Python. It’s not something that’s ready for public use but it’s fine for me. A little git to synchronise things, and everything works fine.
I’ve tried to improve my writing style. As a student at King’s College London I’m fortunate enough to have access to a Writing fellow, who will spend a bit of time reading your work and suggesting improvements. I deliberately sent the fellow some of my worst blog posts and was quite embarrassed when I taken to task! I came away from that meeting with plenty to work on! With a bit of time, I see this as a positive. Negative feedback is important if you want to get better, so long as it’s given in a caring way. I think it’s always good to get someone else to read your writing as you go along, however you can. Speaking of the university though…
Academic papers covered in Latex.
… I’ve been doing a fair bit of academic writing recently as part of my PhD research. Writing a paper is quite a different exercise to any other writing I’ve done before. Firstly, it’s a more collaborative (and political) activity; there are a number of authors with varying responsibility and input. Given that we are still in the grip of a pandemic, we can’t all get around a table with printed sheets and marker pens. Step in Overleaf.
For our paper 3D Structure From 2D Microscopy Images Using Deep Learning, my supervisors and I used Overleaf to collaboratively edit the paper as it went along. We were using the free trial account that doesn’t included versioning, which made keeping track of who had changed what and when they’d changed it hard. Nevertheless, it made working remotely possible.
I’ve always used LaTex as opposed to Word for all my serious stuff. I’m mostly a Linux shop at the end of the day, so Word has never really been an option. That said, I’m told that Word has gotten a lot better over the years and seems to be the default software choice for University I.T departments, tasked with providing for their students. Maybe I’ll give it a look one day?
LaTex takes some getting used to, but it is one of the accepted standards for academic writing. Templates for all the major journals are typically available for LaTex, and while it’s image layout routines leave something to be desired, it does most things pretty darn well. I’ve used TexStudio in the past and would recommend it, if you don’t need a shared editing space.
This is a tricky one! I’ve recently released HOLLy to the public. This is the code that accompanies our paper. I’d love people to run it, and hope they find it useful. It won’t be much good if there isn’t any decent documentation to go with it.
Documenting code is a big topic though. Comments are always handy. I’ve used a particular style in my code, covering every function with it’s parameters, expected outputs and the reason for it’s being. That’s not nearly enough though. I’ve been working on this PhD for over 3 years now, and some of the code I wrote at the beginning of the course I haven’t touched in a long time. Finding a really good README.md in the root directory, along with an example usage command has saved me an awful lot of time!
I put a fair bit of effort into writing the README.md for HOLLy. In the past, we’d have used a simple text file, Nowadays, folks tend to use Markdown, and I can see why. The syntax itself is easy to use and easy to understand at a glance. You don’t need to render it to know what it’s doing which is really rather clever. Markdown renders nicely to HTML and is automatically parsed by sites such as Github. It’s one of these tools I don’t regret taking the time to learn.
Recently, I’ve become familiar with Read the Docs. This system seems super popular in the Python world, so I decided to adopt it for HOLLy. I found it’s use of Sphinx and reStructuredText to be a little annoying at first — why not just use Markdown? But I’m sure I’ll come around to it, and that there are good reasons for these choices. There’s not a lot there at present in my read-the-docs for HOLLy, but I’m sure as folks get using the software, I’ll know what to add next.
There’s an awful lot more to this particular topic. Suffice it to say future Benjamin is very happy when past Benjamin writes good documentation, and no mistake!
There is a lot of advice and support out there for students writing their reports and theses. The first port of call is usually one’s home institution, via a tutor, the library, or some other official body. There are books, blog posts and courses available all over the internet. For my part, I’ve gotten some excellent feedback from the King’s Writing Fellows, as well as a bunch of pocket guides, such as Brilliant Writing Tips for Students, Getting Critical and Planning Your Essay.
Writing out something as large as a PhD thesis takes a lot of planning. I’m still not best sure how to go about it. Nevertheless, paying for Overleaf is a start. That way, versioning becomes a lot easier. That’ll no doubt be important as things go on.
A few folks have recommended Scrivener as a tool for roughing out a larger piece of writing. Sadly, it’s not available for Linux. Instead we have Manuskript. I’ve tried to use it but I don’t really get that much out of it. It does have word counts per section but as far as I can tell, no easy drag-and-drop sections of text feature. It seems geared more towards novels though, so perhaps it’s a great tool, but not for this job?
Writing notes and ideas is a different kettle of fish entirely. For the longest time, I’ve been using a mediawiki install to keep a running diary of all the key points of my work day, each and everyday. It’s a record of my research; some have called it a lab diary. Apparently, in the biological sciences (and I guess, Chemistry as well?) students are taught how to keep a lab diary. This isn’t something us non-lab students are ever taught but I think it’s an absolutely essential thing to do. I tend to look back over these notes for decision points, ideas and things left to finish. It’s been invaluable to me, and if you are in the process of working on a big project, I’d be willing to bet you have something similar.
This bullet point diary style was partially inspired by John Carmack’s .plan files. I don’t make my notes public though, as I think they’d be very boring and of no interest to anyone, but maybe seeing into the PhD science process might be handy for other students? Maybe there is an opportunity here?
But what about more free-form notes? Notebooks are fine and I use several of them to jot things down. But looking back over them can be almost impossible. Recently, a good friend of mine introduced me to Obsidian — a program that keeps all your notes in local storage, but manages various semantic links between them. It uses a form of Markdown as it’s syntax, so headings and links are no problem. Not only that, but you can embed images relatively easily, keeping them stored locally along with the pertaining notes. All of this can be viewed through a handy graph, showing all the connections between the various documents. Super handy!
I’ve found Obsidian to be most ueful in organising my thoughts, sketching out chapter layouts and recording things that need to be grouped by topic as opposed to time. The wiki does a great job for the latter, but when I want to see how ideas connect or rough things out, Obsidian is super handy. I’ve yet to delve deeper into all the features and plugins but I’m looking forward to it.
Writing out scenarios for roleplay sessions is something I’ve tried to get better at. I’ve tried notebooks and my mediawiki install in order to keep track of what happened in a session, how that affects the narrative and where I might steer the group next. I’ve not found anything that works as well as Obsidian. I use it to keep track of the characters, the events and what happened in each session. I can cross reference things a little bit easier. So far, it’s not too bad. What I’d really like is a way to sketch out some sort of arc for each of the major factions, along with their relationships to each other. I’ve not quite figured that out yet. Perhaps there’s a plugin for that?
I still use mediawiki to keep track of the major points, the links to other resources I need for the game and what not. I’m still on the lookout for something a little tighter. Quickly writing ideas down as the game progresses and having them slot into the right place is still an unsolved problem for me. Having a section where ideas can sit for a bit, recalling them when they are most needed would be invaluable. I’ve moved away from Dungeons and Dragons — I consider it to have inferior rules and style — towards Blades in the Dark. Blades represents a more modern approach where the DM has fewer powers and is much more in-collaboration with the players. This does mean a lot more improv, which I find quite difficult. I’d love a tool to help with that.
I’m veering a little off topic here, so let’s bring it back. TTRPGs require thought and writing, but it’s a heady combination of planning, and planning to improv. Lets look at something a little different…
Publishing a book.
I’ve had a secret project on the go for a few months now — helping to get a book published, that has longed languished in the depths of a hard-drive. Desktop publishing isn’t exactly writing I suppose, but it’s related and I think there’s something worth talking about here.
As I’ve mentioned, I’m a Linux shop in the main, so I wanted some Linux based software. I settled on Scribus — a relatively straightforward DTP application (apparently, good enough for some Indian Newspapers!). At first I found it to be terribly annoying as certain expectations were not met. For instance, if you exceed the size of the text box, the box will not resize and any offending text will disappear. This seemed very odd at first, but after a while it began to make sense. There are other small gotchas too, such as the lack of decent templating, the way styles are handled and the print versus layout views. That said, when one considers that this isn’t text editing but publishing, these changes begin to make sense.
The book is almost complete. It’s full of images at high quality, as well as a lot of data (hint hint!). Once it’s sent off to the printers, I’ll be able to come to a conclusion on how all this sort of thing works.
What to write with?
Keyboards! Now here is a topic that folks in the industry get very passionate and nerdy about! There is a whole lot of discussion on what keyboard layout is best, why Chiclet keys are the spawn of Satan, and whether or not Cherry Blues are antisocial and we should all switch to Kailh anyway. I love home-made mechanical keyboards, crazy input methods and voice-to-text. It’s all so very Cyberpunk (but the good kind!).
It’s a bit out-of-scope to talk about keyboards here but when it comes to writing, or coding or anything along these lines that involves a computer, I think it’s worth considering how you type. For a long time, I just sort of winged it! I never learned to touch type and so I developed a bad habit of looking at the keyboard all the time. I could type fast but I only really used two fingers on each hand. After some time I wondered, “should I learn how to type proper-like?”.
I decided to build an Ergodox keyboard and went with blank keycaps. I had three main reasons for this. Firstly, ergonomic keyboards are sold as being more comfortable to type with. I’m not sure if that’s true or not but I did notice that I typed in a rather hunched way. Not only that, one hand would dominate over the other and dive across the keyboard, making my shoulders even more tight than they would be. Having a split keyboard would force me to split the work evenly between both hands.
Secondly, using blank keycaps would force me to learn where the keys without looking. I used to think that folks with blank keycaps were showing off — perhaps even being a bit pretentious — but what did I know? It was hard going for the first month or so. I actually had another keyboard wired in at the same time, and a quick link to the keyboard layout on the web. But, once I’d gotten through the horror of not being able to type my password properly, every-single-time-I-logged-in, I realised I’d become a better typist. I still make mistakes, but I’m using more fingers on both hands, and hardly looking at the keyboard. I think it’s worked.
Finally, blank keycaps were all I could find at the time for a decent price! Oh well!
There are newer designs of keyboard out there that I’d consider if I was doing this again, and maybe I will. I’m not really using the Ergodox to it’s full — I don’t use layers for instance. Maybe, as time goes on, I’ll get better at using it, or try something else entirely.
Dan Luu talks a bit about velocity, and just getting quicker at doing the things you want to get done. His blog posting was part of the inspiration to get me to analyse where the bottlenecks in my own programming and writing habits were. I’d definitely recommend giving his stuff a read and having a look at the folks he references.
I’ve not talked a lot about grammar, being critical, making an argument or writing style. To be honest, it’s not something I can talk about with any real knowledge, at least not yet. Once I’ve gotten the hang of the academic style, I might talk a bit about that.
I’ve been thinking a lot about branching narratives for computer games. I’ve heard of tools like Twine that folks use to create branching stories. This has me intrigued, not just because of my love for TTRPGs but I’d also like to create a serious computer game one day. If I do, it’ll definitely have a decent story line.
I’ve been thinking a lot about how we tell stories and why they are important. I found myself quite enthralled by Joseph Campbell’s — The Hero with a Thousand Faces. I found it to be a tough read — I’m not used to his style. Nevertheless, I couldn’t put it down. Once you’ve read it, you can’t unread it. Other books on this topic have been recommended to me — ones like The Seven Basic Plots by Christopher Booker. I’ve yet to read it, but it’s on the list!
I suppose, having gotten the tools more or less sorted, it’s time to look at what to write. This seems much harder, but most likely, much more important. I’ll see how I get on! Meanwhile, I’ve a thesis to finish… gulp