After recently moving my site from WordPress to Docusaurus, I decided I wanted a comments feature. Not because I got many comments before, nor have I written here in years (something I hope to write about soon), but for the challenge.

Docusaurus is a static site generator (SSG), so self-hosted comments seem impossible. And I find tools like Discus distasteful since they use a single login one can be tracked across multiple domains.

Today I found giscus, and had it set up in less than an hour. It uses GitHub's API to treat the discussions section of a repository as a data source for comments.

While I have my own issues with GitHub post-acquisition, it's a far better solution than tying in Discus, Google, or Facebook to my site. And since I use Docusaurus for professional documentation sites, it's a nice lower barrier to entry for non-technical folks to engage with content, and only one extra click to turn a discussion item into an issue. So my blog made for a perfect sandbox to test it out.

One of the most prominent search result for a guide is behind Medium's paywall, so I figured I'd write up the process myself.

Yesterday was my last day at the company I've worked with for the last 4 years. On Monday I start at my new position. In the meantime, I hope to be a little more creative in my personal spaces; here on the blog, over on Twitch, etc.

Here are some things I learned while job hunting:

I am not a developer, but I work with developer tools all day. This can be frustrating, because a lot of tools made for developers assuming knowledge that I'm lacking.

Of course, if that wasn't the case there would be less need for technical writers and my work would be harder to come by!

In any case, After spending the last few days migrating my job's documentation to use the CircleCI 2.0 configuration, here are some tips I picked up:

I recently switched my personal file hosting/sharing to NextCloud,  from OwnCloud. Among other features and improvements, it will automatically sort uploaded photos from my phone into folders by date. 

This great new feature created a glaring contrast with the many years' worth of previous photos, mostly all in a single directory, some sorted manually by event.  The process of grammatically identifying, sorting, and deduplicating was simple enough once all the tools were lined up, but finding them was not. What follows are the tools I used to get my photos in order.

Hi. Hello? Anyone there? My server broke, can anyone help?

As a regular IRC user, I've seen this message many times. I've also seen the hateful responses these intrusions generate. IRC is an older communication form (relative to the Internet), mostly inhabited by those who've used it for decades, and are set in their ways.

IRC is also where you'll find large communities of people all interested in specific topics, usually tech-related. If you're an expert on MySQL, Ubuntu Linux, Python, etc, you're most likely found in #TOPIC on at least one IRC network.

Which is why there are newcomers everyday, logging on to seek the wisdom of these software gurus. If you're one of them, this post is for you; the IRC amateur who's venturing to Freenode or OFTC for the first time to ask for some much-needed help.

Because of how many great open-source projects have empty readme files.

Because I like open-source software, but I'm not a developer. Even when projects are documented, it's written for other developers. The assumed level of knowledge is that of the person who wrote it. I think like a user, not a dev.

Because when beginners enter issues on GitHub, they're met with scorn instead of compassion. And when answers are given, the goal seems to be to give as little information as possible, and make the user chase down the real answer from clues and hints.

Because I hate being told "RTFM". If I'm asking, I've already read the man page. The problem is, a man page generally only lists the options, and briefly explains what they are. Not how to use them, or why you would want to.

I'm a technical writer because I want to use great software without having to know how it was built in order to use it. Because the high learning curve associated with Linux comes in part because its users hoard their knowledge, and belittle those asking for a helping hand.

I'm a technical writer because I want everyone to be able to use the software they want.

Are you a technical writer? If so, why do you do it?

As mentioned in my last post, I'm taking advantage of this arbitrary point in the Earth's rotation around Sol as a starting point for a renewed spring of educational self-improvement. Since then I've been looking into what online courses to take advantage of. Below are some of my impressions, both old and new, of some of the online learning resources I've dabbled with.

There's a whole group of Linux users out there (myself included), for whom we aren't writing guides for. When you search for answers online, you find one of two types of write-ups: basic instructionals aimed at first timers, and advanced hacks for those who already have coding language or two under their belt.

But what about everyone in the middle? Those who know how to live in Linux, but aren't developers? Can those who develop open-source software put themselves in the right mindset to write documentation for those who don't know what they know? In most cases, the answer seems to be no.

Here's an example: when I was interested in trying out Atom, I found this project, which include syntax highlighting for GitHub flavored Markdown. Great stuff, but how do I add it to the text editor? If I was only to use the maintainer's readme file, I'd be lost on how to use it. Bad form.

On the other hand, here's a project on GitHub from a former colleague with an excellent readme which covers not only installation. but common configurations and usage. Well done!

I've asked around, and I'm not the only one who feels that there's a gap in tech write-ups. That's why when we write guides for Linode </obvious product placement> we specify the prerequisite knowledge and link to those guides, and don't cover anything that's in them. But all new concepts are explained and exampled.

So if you're a member of an open-source project, go take a look at your README. Would it make sense to someone who's never used the language it's written in? Do you explain how to install it, or expect the reader to already be familiar with make? Think about it please.

From now through Sunday I'll be at Pennapps with Linode, giving out swag, Linode credit, and mentoring where I can! I may also try to do some hacking myself, but I'm not sure if I should be reorganizing my services across different servers, or working on a new project.

These hackathons run 48 hours straight, but I don't know how long I'll last. I'll try to update here as the hours pass.

EDIT: This is what I've come up with so far: Python Prime Number Generator

EDIT #2: I've made another couple of useless site: GET SCHWIFTY! and MR MEESEEKS