Jonathan Konrath RSS Feed

Site migration with Codex

Sat, 09 May 2026 00:00:00 GMT

It's probably time I start talking about AI, because it's fundamentally changing everything I do on a day-to-day basis as a manager and tech writer. I'll bloviate on this from a managerial perspective at a later date, but I thought I would start with a basic example.

The problem

This blog was a Jekyll web site, doing the docs-as-code thing, taking Markdown and using a static site generator to spit this out and publish it on GitHub Pages. Good stuff, but because of life, I haven't touched it in... well, years. It happens. But almost four years have passed, which is in web-time is like if I was carving this stuff on clay tablets.

I was sure there was a better approach. I mean, I've gone through three of them at the day job, and I know there's bigger/faster/stronger out there. Also, I have no idea how many blatant security holes this thing might have, how many outdated packages knocked around, how many different ways GitHub changed their publishing process.

But, I'm completely out of touch with the Jekyll world. I haven't used it daily since I left TIBCO in 2021. Not only is there no muscle memory in how the site worked, but I don't know what the cool kids are doing anymore. I have a great Marketing Engineering team at work that's on the leading edge of this stuff and have the daily at-bats behind them to do this. But they don't handle my personal blog, and I've definitely worked in places where I didn't have a dev team dedicated to my docs site.

The old way

Nobody reads this blog and there's no money involved if I mess it up. But let's say this was a docs site at a Real Company doing Real Business. How does the typical update or repair scenario usually go down?

I don't know how to fix it.
I go to a dev group in the company. It's not their job. They have a job and it's at 400% right now.
I go up the chain. A manager higher than me says, "I thought you did that."
I bounce around a few other dev groups. I get either "how does this affect ROI?" or "I've got 19 things on my roadmap that are shipping this month" or "That sounds like a great idea! Let's talk next month" or "I thought you did that."
I consider hiring a contractor. Back to step 3, but "how does this affect ROI? How much does this cost? Don't you have a developer? Did you ask (person from 2)."
Maybe if I look at ancient posts on StackOverflow I can figure this out?
Goto 1.

This is not a good process. And it happens to me like once a month.

The new way

I am a Codex apologist. Claude Code seems to be the cool thing these days, and I use that too. But I'm paying for ChatGPT here at home, so Codex it is.

I fired up Codex, pointed it to my GitHub repo, and asked this:

This Jekyll site hasn't been touched in almost four years. What has changed with Jekyll that may need to be updated, and are there any package or library changes that need to be made?

Codex chewed on this for a minute, ripped through the site structure and dependencies then proceeded to tell me exactly what had changed in the Jekyll world in the last four years. Jekyll 4.2.1 was the new hotness and I was still on 3.10.0. The theme got a bump too, and I had some customization to the theme that needed adjustment. Change those and that changes a bunch of stuff downstream, but that's all handled through the magic of the Gemfile.

GitHub Pages completely changed their publishing method, and I'd either have to stick to the old legacy way or move to GitHub Actions. I totally would have missed this. And I'm sure many fine people work on GitHub's docs, but RTFMing this and trial-and-erroring it until it worked is a week of my life I can't spare. It was amazing that Codex told me all of this, and gave me a plan of action and the steps to take. Now I just had to make a choice on the two methods, and have Codex do the rest:

Align the migration to native github pages dependencies. Do this in a GitHub branch and open a PR

There was a brief stumble with getting the latest GitHub CLI running and then logging in. But otherwise, two lines, done. It created a PR, I gave it a test spin, and then I merged. Flawless.

I cannot emphasize enough how much of a pain it would have been for me to do this myself. Instead of asking permission and trying to explain this in meetings and getting back the wrong thing, I literally typed two lines and had "someone" else do the entire thing to me. If you've been in this predicament before, you can see this is absolutely life-changing.

Bonus points: switching tools entirely

This was awesome and it worked. But let's face it, Jekyll is a bit “is the dress blue and black or white and gold?” date-wise, and I thought, "Why not just move to a newer tool?"

I used Gatsby for years, and I liked it. I absolutely know there are newer static site generators, but Gatsby would be a good test case. So:

This site is jekyll and I want to move it to Gatsby. I would like to change it from jekyll to Gatsby. Let's break it up into the following big tasks:

Create a branch jkgatsby and do the work there, as a PR.

Any structure moves that need to be made to switch to Gatsby, including moves of configs and such.

Use the gatsby starter https://www.gatsbyjs.com/starters/gatsbyjs/gatsby-starter-blog/

We still want to use .md. Do whatever you need to convert in the frontmatter. If _posts isn't the preferred directory for gatsby, feel free to move it.

Build the site with a github action when anything is pushed onto main.

Put a header or menu somewhere that has the about, contact, skills, and resume pages.

Take the twitter reference out of the footer.

Codex took a few moments to sing the song of its people, and spat out a PR. I had a follow-up on getting pagination going, but that was quick. I merged the PR, and had a brief GitHub Actions fail, but when I explained it and Codex looked at my config, and realized that was botched up a bit. It explained a settings change, and I did that, and it 100% worked.

A few years ago, I ran into a similar-but-different GitHub problem with HTTPS configuration. This took days of reading three different conflicting sets of docs, Googling endlessly to find other blog posts that didn't have the right answer, and way too much trial and error. This time, I asked a question, got an answer, had a complete implementation ready to review and merge. Done. Back to work.

There are obvious philosophical, political, and cultural arguments about this. More on that later. But this is an absolute game-changer, and it's completely changing what it means to be a manager, now that I can manage my own AI "team" of developers.

MSML

Sat, 21 Mar 2026 00:00:00 GMT

Usual apologies on me never updating this. 1239 days is a bit of a gap.

So, some catch up: I went back to school for a second master's degree in 2023. A bit about that.

The MBA program I finished at WGU in 2022 overlaps the school's MS in Management and Leadership program with three classes in common. That meant I would have six classes and the capstone project to get a second degree. The basic difference between the MSML and the MBA is the MSML is more soft-skill stuff around leading teams, innovation, and strategy. The MBA is more core business school stuff like finance and accounting, plus classes on project management and a taste of the leadership stuff. I liked the MBA, but figured as a manager of people, I could probably use more leadership work in a structured way.

I'll be honest: I learned a lot of good information in the MSML program, but it was nowhere near as good or as challenging as the MBA. Part of the reason I did this back-to-school thing in 2022 was I didn't want my brain to go to mush, and crossword puzzles only do so much. I also needed to challenge myself and do something hard that I didn't think I could do. Taking finance and accounting with absolutely zero background in either was a really big boulder to roll uphill. Getting past that gave me a real sense of accomplishment.

The MSML? Not so much. The most challenging courses were actually deep-dives on a couple of the most tedious classes in the MBA. One of the "tough" classes, Business Acumen, was basically a junior version of accounting, finance, econ, and marketing rolled up into one course. Two of the harder classes, Strategic Management and Change Management, had so much overlap, the papers gave me a constant "didn't I just write about this?" situation. And this degree had zero math or Excel, but it had two classes that required a recorded presentation, three that involved Powerpoint, and it had a team project.

So, there were two proctored tests, twelve papers total. That included the capstone, which was pretty eh. In the MBA, the capstone project was really cool. You played this simulation where you ran a business, competed against other players, and then did everything from pitch for venture cap to write a shareholder report, That was a lot of fun, to be honest. The capstone for this was an annotated bibliography of three sources per class and what we learned from them, which was mostly tedious; then a giant paper on a training plan; then a speech on that paper. A lot of the papers in this class were pure tedium. A lot of people in this program are in HR, so maybe that's the point.

The one unusual thing about this degree is I ended up working on it in six different countries. I was either cramming for tests or working on papers in Iceland, England, Qatar, India, and the UAE. I particularly remember being up all night in Dubai, sitting in an airport lounge and downing as many free Diet Cokes as possible while pulling articles for that bibliography.

I hate to sound bitter about the experience; I was mostly exhausted by it. I did learn a lot, although I think quantifying that is a bit out of this silo and bleeding into the Work Jon silo. But I did pick up some skills that will be useful in my career. I guess it just didn't challenge me enough. I think I really phoned it in here, and part of it was the return to office, along with the travel. I finished the degree in four months, and probably put half the effort into it that I did the year before.

Another thing about this degree that was a big spoiler alert on the future: the AI situation. For the MBA in 2022, ChatGPT was not a thing yet; I think it launched the month after I graduated. But it was in full swing for the MSML in 2023, and Reddit was rampant with posts about people who were throwing the syllabus and notes into ChatGPT and asking it to write the papers for them. There were also counter-posts about how ChatGPT was making stuff up like fake citations and hallucinatory text. The school used an anti-plagiarism system for papers, but it wasn't new enough to catch ChatGPT yet. The rumor was that these systems would start using AI to detect AI though. That's a fun little arms race that has obviously ratcheted up a bit in the last three years. More on that in another post, I think.

MBA

Sun, 07 May 2023 00:00:00 GMT

I would say it's time for my annual update, but it's like a year and a half now.

I actually started typing this from 40,000 feet above the Pacific Ocean, on my way to Maui last November, where the plan was to not think about technical writing, management, or work for seven days. I did okay with that, and feel free to bug me about my Maui restaurant list if you're headed there. Thanks to Git, I started work on this while I was on the plane. That always seems to be the example they give in Git training, right? "So it's all in your local repo. If you get on a plane and aren't on the internet, you can still work." Right? Well, I never pushed my commit, and I never finished writing, so maybe it's not perfect.

The big update: I completed an MBA last year. This was at Western Governors University, which has a fully-remote, proficiency-based program. It's a neat model for learning; basically, you enroll by the term, but then you finish classes as slow or as fast as you want. So instead of like enrolling in twelve credit hours for a semester, you do as many classes as you want to finish in six months.

I still worked full-time (or more than full-time, really), but I type fast. I was able to finish the two-year program in about five months. I started on June 1, and my graduation date was officially October 24, although I finished my last class about a week before that.

This program was an IT Management version of the MBA, so it contained a few courses specific to IT project management. But otherwise, it had all the same classes as a regular business MBA. (I think I skipped an operations management class, and a public speaking class, which was good. When I was an undergrad and had to take a speech class, I did it at 8 am in a summer session, so it was only six people.)

I think the first question people ask me is, "Why?" I know I don't know any other tech writers with an MBA, and I have never applied for a job that required one. But I had a few thoughts about why I wanted to do this:

I am a manager, and I never had any formal training as a manager. I have spent some time on Udemy watching leadership videos, and I have a whole shelf of half-read management books. But I felt like I needed something that said I was a manager, or at least something more than the few Agile crash course certification badges on my LinkedIn.
I've always vaguely wanted a graduate degree, although never knew how that would happen.
I don't intend to move on to being a CTO or a PM or anything else. But I could see a future someday at some other company where another department got shoved next to the tech writing department (UX? research? QA?) and I would need to manage both. And I'd like to be prepared for that.
I'm not starting a company. But in working at a start-up, I'm constantly inundated with discussion about financing and organization and whatever, so maybe I need to know more about it.
This was way outside my wheelhouse. It would be hard. And I need to do things outside my wheelhouse that are hard.
It's arguably more interesting than doing crossword puzzles in my spare time to keep my brain from turning to goo.

The basic summary of the classwork is that things fell into three buckets:

Classes that were things I do every day without thinking, or have been trained on to the point of absurdity, and I just needed to get them done quickly. There were leadership, ethics, and people management classes in which more than 50% of the content was the mandatory training I have to take every year that says you shouldn't bribe a foreign government.
Classes that were interesting and fun. I took a marketing class where I had to write a marketing plan for releasing Taco Bell menu items in Japan. I also liked the IT classes, which involved things like doing a SWOT analysis for a company to pivot its IT infrastructure to the cloud.
Classes that were climbing K2 without oxygen. I never took any business as an undergrad, and had to face three classes that almost ended me: accounting, finance, and econ. These were classes with math, equations, ratios, and lots and lots of raw memorization of hundreds of terms.

The capstone project, the big thing at the end, was a lot of fun. It basically put everything together and you had to run a business in a simulation for three quarters, competing against other people. A lot of people complained that the situation was insane, but it was honestly like playing Roller Coaster Tycoon for a grade. You had to run a bicycle company and decide on everything: factories, distribution, stores, bike features, R&D, marketing, everything. You had to pitch for venture cap after the first two quarters (which meant I did not avoid public speaking), and you had to write a shareholder report. It was fun making changes to see if I could increase output or sales.

Overall, the degree had five proctored tests and seven papers which totaled about 190 pages. There was some PowerPoint, and far too much Excel. Almost everything else was Word.

(Side note: I do not like Excel. Even worse than using it for legitimate purposes like accounting, I am really not into the standard use in tech writing, which is, "Let's do a doc plan or analysis by pouring every filename into a sheet that is immediately obsolete and then putting a bunch of random checkmarks and notes and names in 17 columns, and then in a month, we will have no idea why we did this." If you're in that situation, use Jira. If you can't use Jira, use Airtable. If you can't use Airtable, you're probably wasting your time on something that doesn't matter and should stop.)

The last time I wrote an academic paper, I think I had to find things in a physical card catalog and then ask a librarian to pull the microfiche for me and pay ten cents a page to photocopy the article. Everything has changed 100%. OK, I use Word (begrudgingly) and get that part. But I'd never used a reference manager to track my citations, and that all magically works, without me remembering where the parenthesis go on an APA7 cite. The course was all e-books, and the papers I had to look up and cite were all online in their library. So, search "Jack Welch GE leadership traits" and find a result in Harvard Business Review, and there's your PDF to skim. Find what you want, and there's a link next to it with the cite. Copy and paste it exactly and you're up against a plagiarism checker that will nail you for doing that. It was all completely different than when I would pay my girlfriend's roommate to type my papers on a Brother word processor for me.

So, what did I learn? I don't know how much of this applies directly to being a tech writing manager. But I think for a person living within the wheelhouse of big tech and seeing finance and business in the news, it's invaluable. Just in general, I think it's twisted my brain on how companies work. The second that Albertson's/Kroger merger was announced, I pulled 10-K reports from the SEC for both parties, drilled down to the balance sheet, and started asking my better half (the consumer packaged goods expert of the family) dozens of questions, like "why does Kroger have almost two billion dollars of cash on hand during a pandemic?" From a practical perspective, I think I knew a lot of the IT management stuff like budgeting and SWOT analysis, but it was nice to do it on paper, and the next time I have to do a major tooling acquisition, I know how to make it look.

WGU was great, too. I love the model, and everyone I worked with was awesome. I talked my sister into going back for her Master's degree in the education school. And spoiler alert, I'm actually halfway done with another degree. More on that later.

Interview question - calculating a factorial

Tue, 26 Oct 2021 00:00:00 GMT

When I was a tech writer, almost every time a developer interviewed me, they would inevitably ask me to whiteboard how to calculate the factorial of a number. When I moved to Northern California in 2008 and started interviewing at various Bay Area tech firms, I was seriously asked to do this exact problem at least twelve times in interviews with three companies.

I thought of this recently after reading this, and thinking of the smart-aleck answers I never did give during interviews, like writing it in PostScript or COBOL.

(BTW, a factorial is the product of all positive integers between 1 and n. It's denoted as n! So 4! = 1 * 2 * 3 * 4 = 24.)

Iteratively

The simple/obvious answer is doing it iteratively. In C:

int factorial(int n)
{
  int i;
  int result=1;
  for (i=1; i<=n; i++){
    result = result * i;
  }
  return result;
}

Extra credit:

That should fail if you called it with a zero or a negative number.
There isn't a main() that asks for a number and prints the result in a pretty way.
If you want to be cute, use the assignment operator result *= i instead of result = result * i and save nine keystrokes.

Recursively

They won't always expect this from a writer who doesn't regularly code, but here's the other way to do it:

int factorial(int n)
{
  if (n == 0)
    return 1;
  return n * factorial(n - 1);
}

You can make this way more incomprehensible with the ternary operator:

int factorial(int n)
{
  return(n==1||n==0) ? 1 : n*(factorial(n-1));
}

...Other

Scheme

I went to Indiana University at a time when the first three or four computer science classes were all taught in Scheme. I always wanted to whiteboard this as an answer:

(define (factorial n)
  (cond ((equal? n 0) 1)
  (else (* n (factorial (- n 1))))))

Extra credit: do it with tail recursion.

Liquid

This blog was in Jekyll, so maybe you've worked with Liquid templates before.

assign n = 20
assign result = 1
for i in (1..n)
assign result = result | times i
endfor
result

(Note: wrap all of those in {% and %} except the last line, which is wrapped in double curly braces. I can't get it to delimit correctly when I put the whole thing in there and it tries to evaluate the expression.)

REST API

APIs are the future (not speaking for my employer, of course) so maybe you want to use a REST API to do it:

curl http://api.mathjs.org/v4/?expr=5!

(Why use cURL though? There's a much better way.)

Standard libraries

If they forget to qualify their question with "don't use standard libraries" you can do this (Python):

import math

def factorial(x):
  print (math.factorial(x))

Commodore BASIC 2.0

Let's take it back to the beginning:

SQL

I was trying to figure this out, but my SQL days are long behind me. You could use a recursive common table expression to create a table of n rows with each row containing the result of the previous row multiplied by the row number... or something.

PDF

This is the point in my research where I had to give up and walk away for a bit. But if you had the right PDF CLI library, you could write a shell script that creates a one-page blank PDF, then iteratively merges copies of that template PDF onto a result PDF and count the number of pages at completion. There's some magic number limit of objects in the PDF specification so they still work on 32-bit machines -- eight million or so -- which means this would break just past the factorial of 10.

Actually, a lot of these would break after about 12, when you'd hit INT_MAX. There's a way to do bigger numbers by creating an array of the number of digits you want to calculate, then writing a multiply function that does all of the carrying when each spot in the array goes past 9, etc. If you really want to push it, use a linked list instead of an array so you won't waste any space. This probably won't fit on one whiteboard.

PostScript

Oh, here it is in PostScript (I don't know PostScript anymore; I borrowed it from here...)

/factorial { 1 dict begin
  /n exch def
  n 0 eq {
    1
  }{
    n n 1 sub factorial mul
  } ifelse
end } def

(The serious answer to all of this, if you're a developer tasked with interviewing a tech writer, is to ask them about their problem-solving methodology, and how they figure things out when they don't know the answer. People who have to write a code sample every other month won't know off the top of their head how to reverse a linked list. They should be able to talk you through a difficult problem they had to solve once, though. It's probably a cross-functional review, right? Test their soft skills, not their ability to memorize. Just my opinion.)

GitHub Pages Custom Domains

Tue, 26 Oct 2021 00:00:00 GMT

I moved this site from Wordpress to GitHub pages a few months ago, and when I got to redirecting the domain, I punted and put an .htaccess file on the old site and 301'ed it over. That almost worked, but after each redirect happened, any old URLs were sent to jkonrath.github.io/, which broke all of my old links. I needed to properly point my hostname to the right place, and this was a bit maddening.

Here's what I did to get it to work. My domain is registered at Pair Domains, and my old site was running at Pair. This assumes you have created a GitHub account and a repo for your GitHub pages stuff, and have an address like I have jkonrath.github.io.

Disclaimer: I'm not an IT professional, and you could mess up everything by listening to me. You probably shouldn't listen to me about anything, let alone something involving data loss. You've been warned.

The Pair part:

Log in to the Pair ACC site. Back up the old WordPress site. Don't forget to back up the database, too.
Go to Domains and select the domain from the list.
Select Delete Domain From Account.

I only needed to do these three things because the domain was pointed at an IP and subdirectory of another host I run there. If you only registered a domain at Pair Domains and don't host the site there, you don't have to do this.
Log in to the Pair Domains site, and select your domain name.
Go to Domain Address Settings. This may be disabled by default; I had to accept terms and turn it on first.
If you have Website Forwarding set, turn that off by deleting the forwarding URLs.
From the Add New Record dropdown list, select CNAME (Parking).
1. In the left side under Alias, put www.
2. In the right, under Points To, put yourusername.github.io.
3. Select Add Record.
Go back to Add New Record, and select A (Round Robin).
Under Host Name, put @ and under IP Addresses, put these four IP numbers:
```
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
```
Select Add Record. You will now have a CNAME for www pointing to your GitHub Pages domain, and four A records pointing to the IP addresses above.

Note: Double-check this nine times. The CNAME is www >> yourusername.github.io and there are four A records that are @ >> 185.199.x.y If you get the www and @ backwards, this won't work.

After you do this, you have to wait. It could be a minute; it could be a day. A good way to test it is whatsmydns.net, which shows how your changes have propagated around the world.

Once that sorts itself out:

Go to GitHub, and open the repo for your blog.
Select Settings, then Pages. It will say your page is being hosted at yourusername.github.io. If it isn't, you've got bigger problems. Sort those out first.
Under Custom Domain, enter the custom domain and select Save. You're putting in www.my-host-name.com. There's no protocol in front of it (http://) but don't forget the www.
This will churn away and check the DNS for you. It will also kick off a request to Let's Encrypt to make a certificate for free. You do not have to pay for anything at Pair or do any other legwork to get this done. The catch is that if you messed up the first part, or if GitHub's feeling grumpy, that creation step will get botched, and you won't get any helpful information, except it won't work.
Leave it alone for an hour or a day, and then you can select Enforce HTTPS and it will (eventually) enable HTTPS.

On the last step: it may give you a byzantine error message, like "Unavailable for your site because a certificate has not yet been issued for your domain." If that happens:

Make sure your CNAME and A records on Pair Domains are correct.
Wait a bit.
Under Custom Domain in the GitHub Pages config, select Remove, then add it again. This will redo the request for a new certificate. Or not. I think I did it five times before it took.

You may need to clear your browser cache or wait a bit more until this works, but test it with and without HTTPS and www.

Atom as a Markdown Editor

Tue, 19 Oct 2021 00:00:00 GMT

(Update: nope. I've since switched to VSC, so looks like you should too. I'll leave this here for nostalgia purposes.)

Part of this switch to Jekyll I mentioned previously is that I now edit this site in Markdown instead of WordPress. The great thing about Markdown is you can theoretically edit it in anything; you could even use Notepad or TextEdit or even the DOS Edlin editor to make a Markdown file. But you probably want something that adds some conveniences, like a few key bindings to save some time typing, a preview pane, and the ability to search and replace multiple files.

When I first started using Markdown at work in 2015, I looked for a good editor that would do all of this, but never entirely found it. I stumbled through trying to set up Notepad++ like an IDE (I was stuck on a Windows machine), and I almost considered setting up Eclipse as a Markdown editor, but then I remembered it wasn't 2003.

I eventually settled on using Atom, which is a text editor-slash-IDE released by GitHub. It's free, open-source, and customizable, with a lot of optional packages that are easy to add.

Here's what I did to set up Atom for my Markdown editing needs:

Not part of Atom per se, but life is much easier when I'm also using GitHub Desktop along with it. It makes it much easier to handle git commits/pushes/merges/branches. Atom does have its own git integration down in the lower right corner, where you see your current branch, do a quick fetch, and see PR review comments.
First thing I do is change the theme, because I can't deal with dark mode (sorry). Go to Preferences > Settings > Themes and pick something; I usually go with One Light, but there are many options.
Then go to Preferences > Settings > Install and grab the following:
- language-markdown - adds grammar support for MD files.
- markdown-writer - adds more MD writing features.
- markdown-preview-enhanced - there are a few previewers out there, but this one seems to work best for me. I had problems with markdown-preview handling Jekyll files; maybe that's fixed now?
Go to Preferences > Settings > Packages and go to the settings for the spell-check package. In the Grammars section, add text.md.
If you File > Open to the directory of your project, it opens it with the hierarchy shown in the left sidebar, and you can then click around in that to open various files.

I've been using this setup daily for a while now at work. But now everyone's using Visual Studio Code, so maybe I need to switch.

Dogfooding

Sun, 13 Jun 2021 18:58:42 GMT

I can't remember when, but I recently heard someone use the term dogfooding, as in a shorthand verb form of eating your own dog food. Every noun in tech becomes a verb, usually when it gets to marketing or sales, but this one made me roll my eyes a bit more than usual.

My wife had never heard the term, which is a bit ironic, since she actually works in the dog food industry. I have mixed feelings about it, although it's marginally better than "drinking your own champagne," because I don't drink, and when I did, champagne was second only to tequila as the alcoholic beverage I disliked the most. But in the late nineties in the tech industry, they would roll out champagne almost as much as they would print team t-shirts. Anyway.

The term "eating your own dog food" is supposed to mean using the tools your company makes to actually operate your company. If your company makes bug tracking software, you shouldn't be paying Atlassian to use Jira; you should be using your own software, to show customers that it actually works.

(Side note: I've always called it JIRA. I started at the new place, and everyone was saying Jira. Turns out the name changed in September of 2017. See here. This is partly the trend of making everything lowercase, and partly testimony to how infrequently the last place updated their software.)

So, the actual news here is that I'm "dogfooding" by moving this site away from Wordpress and doing it all with a static site generator. This is the same docs-as-code approach I do at my job. That means:

Writing everything in Markdown.
Using Atom as my editor.
Using Jekyll as the SSG.
Using the Minima theme with some customization, most notably pagination.
Pushing it all to GitHub.
Hosting it with GitHub pages.

There's lots to cover here, and also not everything is done. My redirect from jonkonrath.com to the new hosted site is a bit of a hack, and I've barely started any page design. I'll get to that, and I plan to explain all of it as I go. But first, I need to go eat something other than dog food for lunch and not think about Alpo.

Onward(s) and Upward(s)

Wed, 24 Mar 2021 01:31:42 GMT

Just a small programming note: after ten and a half years, I left my last position, and moved on to a new one. I’m still managing, still writing, but at a much younger company, which is always interesting.

As per my usual policy, I won’t mention names here, but if you follow me on LinkedIn, you can figure it out.

Also worth mentioning that as always, all words here are mine, and I don’t speak for my employer.

Unrelated grammar nit: I was trying to determine if the saying was onward and upward or onwards and upwards. The first one sounded right to me. Both of the -ward words in question are adverbs with the -s, or adjectives without. (You look downwards; Nine Inch Nails has a great record called The Downward Spiral.)

The saying could be using adverbs or adjectives though, so none of this helps. I think both AP and Chicago Manual of Style would say that Americans would drop the -s and British love to keep it. So, onward and upward.

A quick cmd trick

Sat, 14 Nov 2020 20:34:29 GMT

I wish I could tell the 1990 me that the 2020 me would be posting DOS commands in a blog instead of using a brain-implant computer on the surface of Mars. (I also wish 2020 me could tell 1990 me to patent the idea for an online book store, or that the Reds would sweep the A’s in the World Series.) Anyway, here’s a quick one I should have known already.

You can set the prompt in a command window by setting the environment variable PROMPT. There is a PROMPT command too, which I vaguely remember from the DOS days and setting up an AUTOEXEC.BAT file. But the PROMPT command only works for that session. The variable works for every session.

The default would be PROMPT $P$G: show your current directory, then a greater-than sign, so you get C:\this\that> as your prompt. But you can do some other fun stuff:

$D – the date
$T – the time
$V – the OS version number
$B – a pipe symbol
$G and $T – greater-than and less-than
$S – space
$+ – a plus-sign for each level of depth in the PUSHD directory (If you’re not a habitual user of PUSHD/POPD, look into it.)

There are more; do a PROMPT /? to see them.

I normally set an environment windows by right-clicking My Computer and going to Properties > Advanced > Environment variables, but another fun trick is you can use the SETX command to do this, too. So I did this:

SETX PROMPT=$T $P$G

That adds the time to the front of the default prompt. The reason I did this is because Jekyll builds take forever, and I wanted an easy way to tell if I started the build two minutes or seventeen minutes ago, because time loses all meaning on the last day of a release.

(Thanks: http://www.hanselman.com/blog/a-better-prompt-for-cmdexe-or-cool-prompt-environment-variables-and-a-nice-transparent-multiprompt)

The one-line web server

Fri, 18 Sep 2020 00:38:33 GMT

Every now and again, I run into a situation where a bunch of HTML files can’t be opened by simply double-clicking the index.html, and need to be hosted on a web server to behave properly. I think this used to happen with WebWorks output, and built Jekyll output does this. It’s also sometimes handy to have a web server spinning in the background so you can modify and preview things on the fly.

In the past when this came up, I’d fall down a wormhole about installing the Apache or IIS web server, or trying to figure out where Apple moved the built-in out-of-date Apache web server in the latest version of macOS. (I think it’s gone completely in Catalina.) But instead of sifting through the many different Apache installers and Medium articles about how to get an entire full stack going, I realized this is dead simple if you have Python installed.

First, do you have Python installed? A quick python -V will tell you. If you don’t, grab a copy.

Open a command line in the directory you want to serve up, and if you have Python 3, do this:

python3 -m http.server

If you’re a Windows user, that is probably python and not python3.

If you’re still using Python 2, do this instead:

python -m SimpleHTTPServer

Now point a web browser at localhost:8000 and there’s your stuff.

If you’ve already got something on port 8000, put another port number after the command, like python3 -m http.server 90125.

Don’t expect to run your Fortune 500’s production environment on this. It’s great for testing, though.

(Thanks: https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server and https://docs.python.org/3/library/http.server.html)

Various Cabin Fever Projects

Sun, 23 Aug 2020 19:35:26 GMT

Due to cabin fever (or whatever you call it), I’ve been working on a lot of oddball programming projects. I mean, I’m working way too much at the day job, because I can’t really leave the house, so I’m always on. But I’ve also been doing various things (and then not finishing them) mostly because I don’t have a basement where I can start building a boat out of matchsticks or something.

Anyway, here’s a partial list of what’s on the various back burners of my stove. If you’re really insanely curious about any of these, let me know and maybe I’ll actually finish them.

I’ve been messing around more on GitHub. I’ve been doing this at my job too, but I’m trying to make an effort to be more active on my personal profile. If you have the time and you use any open source software, I’d encourage you to do the same. Even if you’re not a programmer, it’s good to know how to complain about their documentation and maybe fix a few things if you find them. My personal profile is here: https://github.com/jkonrath
GitHub has caused me to dig up all of the various college coding projects and see if they’re worthwhile to post on there, just for kicks. They are all fairly horrible, so no. I’m almost tempted to post the first coding project I actually got paid to do, which I still have. It was for the USGS and it did something with well depth analysis, which I totally don’t understand. The code itself is an exercise on how to not to do what we’d call Big Data analysis now, and would probably be about ten lines of Python. Fun nostalgia though.
Just for kicks, I started writing a Markdown to HTML program, but decided to do it all in straight-up C, using C89 ANSI C and the standard library, nothing more. Outside of Arduino C, I haven’t done much C program in… a long time. I realized why when I started working with strings. I have a newfound appreciation for Python’s built-in string support.
I also realized, digging through the archives, that I know more XSLT than I realized. I posted a gist about this on GitHub, but I probably should make a whole project that’s a collection of all the dumb little building blocks I used constantly when I did this on a daily basis. (Like I always have to look up how to split one file into many files. I need to write that down somewhere.)
I found this giant XSLT I used at a previous job to chop up Doxygen’s XML output and convert it into something I could pull into a structured FrameMaker doc. Looking at it, I’m not sure how useful it is, because I was doing a bunch of arbitrary reordering of the doc because… well, let’s say just because.
I also started working on an XSLT to convert WordPress output to a Flare document. I really do love that Flare documents are just XML, and you can do anything with them.
I converted this blog to Hugo, but in the process I realized it’s faster for me on a site this small to keep it in WordPress, so I didn’t use the conversion. It was a fun learning process, though.
I’ve been messing with ArchiveBox, which is a neat idea. It’s a system where you feed in URLs and it archives them in various formats. It’s sort of a DIY Internet Archive. I’ve been learning more Docker by running it with Docker-compose, and complaining on their GitHub page about various minor problems. I should spend some time helping them rewrite their docs.
Another site where I should pay more attention is Stack Overflow. I’m on there at https://stackoverflow.com/users/99038/jon-konrath. Funny to look back at all the FrameMaker and Doxygen posts I was answering way back when.

Speaking of obsessively building stuff in your basement, this is one of my favorite videos ever: https://vimeo.com/166403522

PDF Printing with Headless Chrome

Mon, 22 Jun 2020 00:07:21 GMT

I’ve got docs for a bunch of products in Jekyll, written mostly in Markdown, but also some HTML output from DITA and Flare. It works great, but doc reviews are a nightmare. We typically use Acrobat shared reviews for doc review, which mostly works, but the question became how to make PDFs of this stuff, especially the Markdown.

There are a lot of obvious and not-so-obvious half-answers here. Like, why not save as PDF from your Markdown editor? (You don’t get any of the templating from Jekyll, and none of the variables show up. You also have to do it from each file, by hand.) I spent years chasing a good solution for this, and tried Pandoc, Prince, PrawnPDF, wkhtmltopdf, dita-ot, and gotenberg, hitting some roadblock with each one.

My short-term solution was starting Jekyll locally, going to each page in a browser, doing a Ctrl-P, and printing to a PDF. For every page. Every single page. For every review. That was obviously not a great way to handle it.

This is when I found something genius: Headless Chrome.

Basically, headless Chrome runs the Chrome browser in the background, and then you can throw commands at it and get the output. If you ever used the venerable DZBatcher back in the day for non-interactive FrameMaker, it’s a similar concept. If you’re a Node programmer, there’s a bunch of crazy stuff you can do with it. But there’s also a command-line interface where you can do some basic stuff from a shell script.

If you have a version of Chrome newer than mid-2017, you’re set. You can do something like this:

chrome --headless --disable-gpu --print-to-pdf https://www.jonkonrath.com/

Another fun command is --screenshot, which will dump the page to a PNG.

There are a bunch of caveats, and there is almost no logging or error messages thrown by Chrome, so it’s maddening trying to debug this. So keep the following in mind:

Headless Chrome uses the location of your Chrome binary as the working directory, and tries to save files there. If you’re using Windows, chances are you can’t write files in C:\Program Files (x86), but it won’t tell you that if it fails. And if it does work, it will pollute that directory with output as you wonder where it’s putting the PDFs. You can specify an output file with --print-to-pdf="/full/path/file.pdf" and give a full absolute directory there.
There is an --enable-logging switch, which is vaguely helpful.
The URL you specify has to have a protocol in front of it (http:// or https://) or it will silently fail.
If you do something wrong, Chrome will go sideways, but keep running in the background without complaint. You’ll need to stop every Chrome process to get it to work again.

I can’t publish the Windows CMD script I wrote for two reasons: one, it belongs to my employer because they pay me, and two, it’s the worst piece of garbage you’ve ever seen. The five lines of code I had to write to generate a timestamped directory look like if one of my cats slept on my keyboard for 45 minutes. Anyway, what I basically did:

Pass in a .txt file with a list of URLs in the order I eventually want the output.
Create a new timestamped directory.
Loop through the text file, and run the print-to-pdf command once per line, dumping them into the timestamped directory.

When I named the output files, I stripped off the protocol and hostname from the URL, and numbered the files, and replaced the slashes with dashes in the file. So if I printed http://example.com/this/is/the/index.html, it would create 1-this-is-the-index.html. The path thing is so duplicate files don’t overwrite each other.

Then when I have that directory of PDFs, I Ctrl-A, right-click, and combine the files into a PDF, then run a shared review on that. The beauty is that when I do round two of the review, I simply run the script again, and the files are in the same order. (Otherwise, the files are going to be in alphabetical order, which probably isn’t what your reviewers want.)

A handy way to get that file started is with a dir /b > file-list.txt from the command line in your top-level source directory. Don’t forget to edit out the images and directory names from your list.

This isn’t a great way to do production-ready PDFs, and you’ll have no good control over headers, footers, page layout, or anything else. Also, all of the links in the PDF won’t work right; they’ll go to localhost if you’re running Jekyll locally. But it’s close enough for review purposes.

More info on Headless Chrome: https://developers.google.com/web/updates/2017/04/headless-chrome

xml.etree.ElementTree and OS randomness

Tue, 05 May 2020 22:28:21 GMT

OK, I’ll start by doing something you aren’t supposed to do: parse HTML using a bunch of regular expressions in Python. Don’t do this. Life is too short. Use something like BeautifulSoup. I couldn’t, because I had to use standard libraries only, so here I am.

Anyway, my program manipulated a tree of XHTML using xml.etree.ElementTree. Typical stuff like any tutorial on it:

import xml.etree.ElementTree as ET
...
root = ET.parse(htmlfname).getroot()
bod = root.find('body')
...

Then after a bunch of scraping, I used a regex like this to get the address in the href of the link:

anchor_addr = re.search("<a href=\"([^\"]*)\"",anchor_base).group(1)

(I’m converting HTML to Markdown. Don’t ask why.)

Anyway, this worked fine on Windows. I pushed the code, and a Unix machine in the CICD pipeline built it, and failed on this line. The match would fail, and anchor_addr wouldn’t have a .group(1), because it was a NoneType.

At first, I thought it was the typical problem with linefeeds, like my code was splitting strings into arrays with \n and on Windows it had \r\n. After messing around with that, I found it it wasn’t the case.

Here’s the problem: xml.etree.ElementTree uses a dictionary to store the attributes of an element it parses. Python dictionaries are inherently unordered. Or they can be unordered; it’s an implementation detail. And it looks like the version of Python I was using on Windows was ordering them, but the ones I was using on my home Mac and on this unix build machine were returning the attributes alphabetically. So <a href="foo" alt="hi"> was becoming <a alt="hi" href="foo"> and breaking my regexp.

My code didn’t really need to find the entire element and pull the value of the attribute, because it was already inside the element. So I was able to change that regexp to "href=\"([^\"]*)\"" and that worked, provided it was never HREF or HREF='foo'.

Long story short, don’t use regular expressions to parse HTML.

A few quick updates

Tue, 05 May 2020 19:43:51 GMT

Five years, five updates. Sounds about right.

A few quick updates, in the interest in posting more than once a year:

I’ve been managing other writers for almost four years now, so I should probably change my byline to reflect that. I’m still writing and working on tool/architecture stuff. But at some point, I should write down some snappy articles with management tips and tricks. Maybe some stuff on synergy and paradigm shifts.
My byline also mentioned being a FrameMaker nerd. I’ve barely used FrameMaker in the last five years, except to get stuff out of it. Aside from a few things still lingering in *.fm files, most of my company uses DITA, and some of use Markdown and Jekyll. But the eventual plan is to move everything to MadCap Flare. So maybe I’ll write about that more later. For now, strike FrameMaker from the byline.
I’ve been doing some programming lately, mostly in the quest to get a bunch of DITA converted over to Flare. Whenever I’ve run into a conversion or production program that required custom code, I’ve always said “I’m not a programmer” and then spent months trying to get developer time to fix it. I think it’s time I change that to “I’m not a very good programmer” and work on improving that. As of late, that’s involved a lot of Python, so you may see some posts on that.

Of course, I’m saying all of this, and I may not post again until 2024 because I’m so busy. But, stay tuned.

Git choose-your-own-adventure

Sun, 10 Mar 2019 18:03:13 GMT

I use git on a daily basis. Not to age myself, but I went from rcs to cvs to svn to git, with some Perforce and SourceSafe sprinkled in there, so I have a long background in source control. But git is just different enough to throw me sometimes. And for whatever reason, a lot of git documentary gets a bit, well, academic. It’s hard to find a quick answer sometimes, and they’re often buried in very theoretical arguments about whether or not git submodules are essential or the worst thing since Agent Orange.

Anyway, here’s my go-to for answers when I break something: http://sethrobertson.github.io/GitFixUm/fixup.html

There are two things I like about this page. First, it gives you answers without a lot of guff. Less is more, etc.

The second thing is that it’s presented as a choose-your-own-adventure. Are you trying to do this? Did you do this? Do you want to do this? It’s a simple troubleshooting flowchart, something I’ve written in docs before, and something you’ll run into every time you call tech support. (There it gets a bad rap because the first steps are always “did you try restarting?” and that seems insulting. It’s also the problem 90% of the time. That’s another topic, though.)

But as a kid who grew up devouring Bantam books from the book fair at my grade school, and memorizing _The Cave of Time _way back then, there’s something very intuitive and appealing about this form of docs. I’m not going to say this makes a git branching disaster where you think you lost everything fun, but it makes it easier to drill through the problem and find a solution. I don’t really have any docs at work where I could pull something like this, but as docs in general become more informal and user-oriented, this would be a great format to use.

Contributing to Open Source

Fri, 07 Sep 2018 22:34:55 GMT

One of the questions I’m always asked is how to get experience in tech writing. It’s a chicken/egg problem: you need a job to get experience, but you need experience to get a job. You can attend a code camp or complete a certificate program to get some real-world experience to add to your resume, but what I always tell people is to get started with open-source software.

There is a lot of open-source software out there these days. I got started in computing before this was the case, but was an early adopter of the Linux OS in the early 90s, which changed everything. Now, entire communities have sprung up around the development of operating systems, servers, programming languages, and desktop software. Tools like GitHub have centralized participation, putting source code in a centralized location, and providing tools for quick communication about projects, instead of crufty old mailing lists. It’s made it very easy to explore projects and contribute to them.

Here’s a great article about how to get started on this:

https://medium.freecodecamp.org/contributing-to-open-source-is-not-hard-here-is-my-journey-to-contributing-to-nodejs-d10760e31194

This example is specifically about a developer contributing to the Node.js programming language. But there are a lot of opportunities for tech writers, because documentation for projects is not always that great. The only issue is that there aren’t always that many documentation bugs listed in projects. It requires hunting down a project you like (check out the “explore” section of GitHub to browse through things) and deciding what needs improvement.

Overall, it’s a great way to gain experience, and also improve tools that everyone will use. And, maybe you’ll someday get a job out of it.

Gray/Grey

Mon, 15 Jan 2018 15:30:09 GMT

I wish I had learned this forever ago:

If you are in America, it is gray
If you are in England, it is grey

It’s that simple.

(I partially blame this confusion on Fifty Shades of Grey.)

FrameMaker and the Kinesis Advantage Keyboard

Wed, 08 Jun 2016 22:51:49 GMT

Because of RSI, I use a Kinesis Advantage keyboard. I used the Microsoft ergonomic keyboards for a while, but I’d burn one out every year, and the membrane keys are a bit mushy. I went whole-hog and spent the money on the Kinesis, which I don’t regret at all, except for one thing: the function keys. The F-keys and Esc are little rubber chicklet keys reminiscent – I’m dating myself here – of the Atari 400. And when you’re in FrameMaker and doing some heavy formatting, those keys are essential.

You can remap keys in the Kinesis at the keyboard level, but I switch between Windows and Mac machines through a KVM switch, so I wanted to avoid that. Instead, I use AutoHotkey, a nifty little free Windows utility that enables you to easily remap keys at the OS level.

Head over to https://autohotkey.com/ and grab a copy. My AutoHotkey.ahk has the following entries for FrameMaker:

Home & 5::Send, {F8}
Home & 6::Send, {F9}
End::Send, {Esc}

I don’t use the Home and End keys much, so I stole them for my own use. On the Kinesis, they are in my left thumb cluster, and great for frequently-used combo keystrokes. So I map:

Home-5 to F8. That opens the character designer.
Home-6 to F9. That opens the paragraph designer.
End to Esc. I use Esc constantly for Frame shortcuts, most notable Esc-j-j to repeat a paragraph assign, and Esc-c-c to repeat a character assign.

AHK can do a lot more stuff, like assigning keys to modify and paste the clipboard, run macros from DLLs, and more. If you have a highly repetitive text massage job you can’t tackle in a script, check out the advanced options. But it’s easy to use for a few quick remaps.

Adjusting Mic volume from the command line in Windows

Thu, 10 Mar 2016 02:58:58 GMT

I spend a lot of time in meetings on a USB headset. I have a Windows computer. So every day, multiple times a day, here’s the drill:

Plug in headset.
Mic volume is a random number.
Right-click Sound.
Wait for the right click to register, because half the time it doesn’t, and the lag is horrible.
Select Recording Devices. See last step about lag.
Click Microphone.
Click Properties.
One in ten times, this will cause the control panel to gray out and freeze, so wait five minutes and/or force quit it and start over.
Click the Level Tab. (It’s not the first tab, so this takes ten seconds to scan.)
Change the level back to 100.
Click OK.
Click OK.
Feel the great joy in knowing you’ll have to do this three or four more times that day, which adds up to like 18 months of your life.

The same process on a Mac:

Plug in the headset. It remembers what you had the level set to the last time it was plugged in.

There is a great way around this. It’s called NirCmd, and it’s a great little free Windows command-line executable that enables you to do all sorts of weird things from a command prompt or batch script.

Go grab a copy of it at the above link. The first time you click on the exe, it will ask to copy itself to your Windows directory, and then it’s in your path, ready to go. Create a .bat file like this:

nircmd setsysvolume 65535 Microphone

Each time you put in your headset, run that, and you’re good to go.

Nircmd also has some commands for shutdown/reboot/standby/logoff if you are sick of digging in the Windows menu for those commands.

REST API Doc article

Tue, 12 Jan 2016 02:16:24 GMT

I think the big problem with API docs is what to document. And it usually ends up with a comment per method, where you have “createFoo = creates a foo; deleteFoo = deletes a foo” and no real content. The question always becomes “well, what else?” And the real value of API docs is everything in between, the things you can’t infer by just looking at method signatures.

The following article is a good list of the other things you need to cover. It talks specifically about REST, but holds true for other API types, also. The TL;DR: what does a consumer need to know to actually use this API? How do you do auth? What are the business uses? What standards does it really follow? What are the other gotchas? What are the SLAs or other requirements for the service?

https://dzone.com/articles/rest-api-documentation-part-1

The hoarding of 25,000 manuals

Tue, 18 Aug 2015 16:36:03 GMT

I started tech writing right around the time print was dying. My first job involved writing software documentation as a manual and as WinHelp, and it all went electronic after that. I also briefly wrote for print books about Linux and Emacs. So I have a box with versions of those manuals, and that box has bounced across the country with me, and is currently sitting in a storage space I never visit. But I always think about that chunk of print in storage, and what the end game is there. As I get new pieces of electronic junk in my life, I try to save the PDF versions of the manuals and get rid of the paper, but there’s a certain something about the print versions, too.

Anyway – Jason Scott of the Textfiles web site recently ran into a seller of manuals who was going out of business and was going to junk an insanely large archive of print books. It’s an impressive collection of old print books going back to the 30s, apparently old radio equipment or parts manuals and whatnot. The owner gave him carte blanche to grab whatever he wanted, and he’s currently stuffing everything he can into a storage space for later dissemination.

Check out the photos of the effort – this is some real print manual pornography, if that’s your sort of thing: http://ascii.textfiles.com/archives/4683

There’s also a paypal to help him cover the costs of storage and shipping and whatnot, if you want to chip in a few bucks for this massive effort to save some classic dead trees.

Removing the Adobe Update Installer from the Mac menu bar

Tue, 11 Aug 2015 16:41:13 GMT

So at some point, Adobe Creative Cloud added a second notification to the menu bar on my Mac. There’s already one that opens the CC app, and always sits in the menu bar. And everyone else wants something in the menu bar. But Adobe started showing this second icon, with a perpetual 1 next to it, even if there were no updates, and all it does is open the first one. No combination of preference-toggling would make it go away, and neither would quitting CC.

Here’s what I had to do:

Quit Creative Cloud.
Rename Applications/Utilities/Adobe Creative Cloud/ACC/Creative Cloud to Creative CloudX.
Go to the new weird menu bar thing and select Open Updater.
You’ll see the old Adobe Updater. If you see the new CC app, you did 1-3 wrong.
Go to Preferences and and turn off Notifications.
Un-rename the file you changed in step 2.
Start the CC app.
You probably have to repeat this every time Adobe issues an update, which will be in like five minutes.

Apple Notes.app and google account with two-factor security not working

Mon, 13 Jul 2015 18:18:22 GMT

So you’ve done something, and the Notes app on the Mac won’t log in to Google anymore. It will sit and spin on a “logging in” forever.

Oh, and you’ve also just turned on two-factor auth in Google. Well, that’s the problem.

Google considers Notes to be a “less secure” app, and it won’t work with two-factor. What you need to do is create an app password, and then it will.

(Not saying two-factor auth is the problem. In fact, you should probably use it for everything.)

Making Yosemite Readable

Fri, 19 Jun 2015 22:37:32 GMT

I resisted the upgrade to Yosemite, even though I have a pretty new mid-2014 MacBook Pro, because I’d rather let someone else beta-test things before I upgrade. When I finally did upgrade, I noticed a problem: my eyes were killing me. Granted, I’ve put a few hundred thousand miles on my eyeballs over the last few decades, but this was a sudden and marked problem.

I think there are a few things going on here, but the big two are the layout and the font. There’s a lot more brightness and transparency in the general look and feel of the layout. And Yosemite switched system fonts, from Lucida Grande to Helvetica Neue. They’re both sans serif fonts, but for whatever reason, the Helvetica taxes my eyes way too much.

I was reluctant to do anything. I hate customizing my system, because then when I change computers, I have to re-remember everything I configured, and I don’t want to be one of those people that has a freaky version of Windows 8 that’s customized to look like Windows for Workgroups 3.11 with a yellow on pink interface and the fonts in Papyrus, and if I can’t get that, I can’t work.

But, anyway, here are a few fixes I messed with:

Select** System Preferences > Accessibility > Reduce Transparency** (This is true by default if #3 below is also true. This can also allegedly speed up UI lag.)
Set System Preferences > General > Appearance to Graphite
Select System Preferences > Accessibility > Increase contrast.
I don’t do this, selecting System Preferences > General > Use dark menu bar and dock might be to your preference
Change the system font back using this: https://github.com/schreiberstein/lucidagrandeyosemite

Photoshop CC Keyboard Shortcut Cheat Sheet

Fri, 29 May 2015 14:47:05 GMT

It seems like the days of cardboard key templates are over – they were a huge thing back in the old days when I started as a consultant in the computer labs back in college. Most of the cool kids would memorize everything, but more of the “returning” students would overlay the laminated cut-outs over the function keys for WordPerfect or Lotus 1-2-3.

Anyway, I’m only an occasional Photoshop user – touching up screenshots, and making dumb collages of friends’ heads I post on Facebook. So I never remember anything. Here’s a great download for Mac users of Photoshop CC. (There’s also a Windows version mentioned.)

http://petapixel.com/2015/05/28/photoshop-cc-2014-keyboard-shortcut-cheat-sheet-for-mac-users/

Blank Markers in FrameMaker

Mon, 20 Apr 2015 08:00:05 GMT

Here’s a FrameMaker problem I had once on a 64-bit Windows machine. I don’t remember having it on my next Win7 machine, but I’ve seen it more than once.

The problem: the marker symbols were missing. These are the little “T” symbols you normally see when you insert a cross-reference or an index marker.

The solution: I did not have the fm5font.ttf font installed. I don’t know if the installer skipped it, or I did an install when I was supposed to upgrade, or I was just holding it wrong.

You can find this font in C:\Program Files (x86)\Adobe\AdobeFrameMaker10\fminit. Double-click it to install, then reboot.

Read the Docs

Sat, 18 Apr 2015 16:00:11 GMT

Here’s something neat I found recently, while looking for some api docs. It’s been around for a while, but you might not have seen it if you don’t work with Python much.

Check this out: https://readthedocs.org

It’s a documentation repository, and you can find docs for a lot of Python projects there, in one searchable place. And you can host docs for your own project there, too.

But what’s neat about it is you can author your docs in reStructuredText or Markdown, and have them built for online reading, or as an ePub or PDF for download. You can import docs from source control systems like git or subversion, and use hooks to automatically rebuild every time you push code.

This is a pretty cool project with a lot of other features, and totally free, although you may want to help them out with a few bucks, too.

The FrameMaker Text Inset Header Problem

Wed, 15 Apr 2015 08:00:34 GMT

Here’s a FrameMaker thing that burns me once a year, usually a few hours before a release.

So, you’ve done this:

Created a text inset file that begins with a Head1 paragraph style.
Inserted that file as a reference in another file, at a point where the paragraph style was Body.
Did a book update, and a blank Head1 was magically added right after the inset, causing a blank entry in the TOC. Didn’t notice this until after the book went to QA and they asked why this keeps happening.
Went to the file with the reference, changed it back to Body, regenerated.
Repeated step 4 for an hour or two and ended up throwing your computer out of a window.

Here’s how to get around it:

Delete the reference in the file and start over.
On the line where you add the inset, make that line consist of nothing but a single nonbreaking space (Ctrl-space).
Move the cursor/insertion point to right BEFORE the nonbreaking space and do a File > Import to add the inset.

The Hello, World Post

Wed, 15 Apr 2015 05:10:45 GMT

Hi and welcome to my page. This is mostly a “blog about this insane little problem so I’ll remember it in a year,” but maybe some of these factoids will be useful to you, too.

Click on any of the above to learn more about me. Or keep scrolling to see my current blog posts.

Thanks,
Jon