Jake LaCaze

writings about writing and other stuff too

Today I spent a couple hours watching Peter Gruenbaum's course Learn API Documentation with JSON and XML on LinkedIn Learning.

While I know watching these lessons has not made me an API documentation expert, I was pleased to learn JSON and XML are not as scary as I once thought. XML in particular feels familiar to anyone comfortable with HTML.

My challenge going forward will be finding opportunities to practice and get something close to real-world experience.

Eyes open

Wonderpath and goals

This morning I had a Zoom chat with Tanya Sharma of Wonderpath. Wonderpath, in early access, is a platform for creating and tracking personal goals and development. Tanya guided me through the onboarding process and asked for feedback.

I set goals related to writing, which you can view and give feedback on here if you're interested.

I've been diverting from my norm and getting out of my comfort zone by testing out up-and-coming platforms—I was active on Racket for a while before shifting my attention to Polywork.

I've enjoyed seeing people try new things and giving feedback where I can. Every situation shows I have something to offer and gives me the opportunity to help in whatever ways I can.

#technicalwriting #learninpublic

Sticker on my coffee pot

#emergencycoffee #linklist #writing

I hope you've already bought all your gifts, because these supply chain issues are putting a damper on the holidays. Especially if you're in the market for some Tomoe River paper...

Articles

If You Have Writer's Block, Maybe You Should Stop Lying — Stop lying about who you are, and write the things that are actually inside you.

Stop Talking in Technical Jargon — Jargon causes a problem when you are talking to someone who doesn't understand it, or, worse, misuses it.

The actors did not make it up — Stop giving actors credit the writers deserve.

Nuts and Bolts: “Thought” Verbs — Chuck Palahniuk forbids you to you use thinking verbs. No more thinking or knowing or understanding or realizing. If your characters are thinking, they're spending too much time alone.

Videos

How to find your audience — and why you should. — The unfortunate truth is that most people won't care about your passion project. Danny Gregory tells why we should focus on finding those who do actually care rather than try to please the masses.

Me drumming with some toys Me drumming with some toys

If pressed to list my writing influences, these days I would credit the likes of Bret Easton Ellis, Cormac McCarthy, and Joan Didion. But my original influences came not from the world of prose but from music, in the form of The Cure's Robert Smith and Joy Division's Ian Curtis, both of whom showed me with their lyrics just how moving words could be.

As a teenager, I thought good writing required perfect grammar, but Smith challenged that view as he sang lines like “Hold me like this for a hundred thousand million days” while Curtis showed me the beauty sometimes waiting in the darkness:

So this is permanence Love's shattered pride What once was innocence Turned on its side...

These two lyricists proved just how important wordsmanship was, and so, whatever I wrote, I sought to find the words worthy of these heroes.

And then I discovered shoegaze via My Bloody Valentine.

I've always had trouble understanding song lyrics, but shoegaze, with its vocals often mixed lower than the instruments, presented more challenges for me. With shoegaze, it wasn't so much that I couldn't understand the lyrics so much as I couldn't hear the lyrics, as they were washed out by everything else happening on the track.

What the hell was going on?

Curiosity led me down a rabbit hole of research via my dialup internet connection. I found an interview in which Kevin Shields of My Bloody Valentine explained that vocals are just another instrument and should be mixed accordingly.

Shields's point stuck with me and began shaping how I viewed art. I started dissecting and deconstructing art rather than simply consuming. And as I learned about taking art part, I began learning more about putting art together. I started looking at all the parts that make the whole.

And lately I've been pondering all the parts that go into writing.

How does style come into play?

Words are obviously a crucial part of writing, but the words themselves are only one part of it.

Does the writer user proper grammar? Does the writer use slang? Proper capitalization and punctuation? Does the font choice matter in this particular medium or project?

Maybe the words themselves aren't as important as the actions depicted. Or maybe the writing is more about the words under the words.

There are countless ways to make an impact through writing.

#essays #writing

letter box at the Magnolia Hotel in downtown Dallas Letter box at the Magnolia Hotel in downtown Dallas

Why should developers be the only ones who get to have fun with GitHub repositories? Writers can get in on the action too.

The point of this post is not to teach you how to use git and GitHub. You can find other resources to help with that. I intend only to explain why GitHub might be a good option for hosting Markdown files for cross-platform writing.

The problem

My digital writing workflow was straight forward as long as I was using only devices made by Apple (Mac mini, iPad, and iPhone) and could sync all of my Markdown files via iCloud. However, I ran into a problem whenever I re-purposed an old Asus laptop by installing Fedora 35, converting the laptop into a Linux desktop. (I call it a “Linux desktop” because the display no longer works, but the laptop projects onto an external display via the HDMI port.)

I knew of no way for a Linux computer to sync with iCloud, so I had to look for a third-party syncing solution.

Failed options

Following is a snapshot of some other options I tried before settling onto GitHub.

Dropbox

Technically, Dropbox could have worked—if I were willing to pay $9.99 a month (or $11.99 a month if I didn't pay for a year upfront.) for the Plus plan. But I didn't want to pay just for syncing Markdown files. It's not as if I have a huge library taking up gigabytes of storage, so anything more than $2 a month feels like a waste of money.

I could have stuck with the free plan if I were willing to limit myself to only 3 devices. But I instead chose to stick with my 4:

  • Linux desktop.
  • Mac mini.
  • iPad.
  • iPhone.

I also considered Dropbox Paper. While Paper does respond to some Markdown, I ran into a couple issues:

  • Paper didn't recognize links written in Markdown. (What other problems would I run into if I used Markdown beyond headings?)
  • Paper doesn't save files in Markdown.

I appreciate that Markdown allows flexibility for editors—I don't want to be locked into a certain app or ecosystem. I write my Markdown files in iA writer on Mac and iOS. iA writer does not have a Linux client, so on Linux I use Typora.

Box & Google Drive

Box looked like a great option, especially since I have 50GB free due to some promotion from a few years ago.

But Box doesn't have a Linux client. And using WebDAV has never seemed reliable to me.

Also, Google Drive no longer has a Linux client. Boo!

Obsidian

I considered going the second brain route with Obsidian, but Apple devices sync Obsidian vaults only via iCloud, unless I want to pay $8 a month for Obsidian Sync.

No, thank you.

Nextcloud

I considered using Nextcloud to host my own cloud on a VPS like DigitalOcean or at home on my own Raspberry Pi. But I've been down that road before and know that I don't want to be responsible for maintaining my own server.

GitHub to the rescue

After the failures listed above, I decided to give GitHub a shot. And I'm glad I did, because the process couldn't have been much easier.

Using GitHub to host my Markdown files has required:

  • Creating a private repository for my files.
  • Using git for syncing the repository on the Linux desktop and Mac mini.
  • Using Working Copy for syncing the repository on my iPad and iPhone.

Perhaps I would not have been so quick to go with GitHub if I hadn't already paid $19.99 for the Pro version of Working Copy. But the price of the Pro license is comparable to two months of Dropbox's Plus plan, so this solution would still make sense.

Concerns

Despite being happy with my choice of using GitHub, I would be dishonest not to mention some concerns with this solution.

Syncing is not automatic

Syncing via GitHub is not a big deal. Just execute a pull or a commit and a push, and you're good to go. That said, I could forget to push on one machine and then jump to another machine, unable to access the latest version of a piece of writing on that original machine.

Fortunately, I'm not working on any mission critical projects. Worst case scenario, I might take my iPad to the coffee shop and be inconvenienced because I can't access the latest file version I edited on my Mac mini or Linux desktop. That's a risk worth taking.

No internet

This problem kind of plays into the point about syncing not being automatic.

What if I'm out of the house with my iPhone or iPad and do not have reliable internet, meaning I can't pull and update from my GitHub repo?

Conclusion

While my concerns are valid, I am fortunate that I am hardly ever without internet or in a situation where forgetting to sync would be detrimental. Also, I am not currently working on anything critical that could not wait until a later date, even if my anxiety makes me forget that at times.

#writing #git #GitHub #technicalwriting

me looking my best at Bird's Fort Trail Park in Irving Me looking my best at Bird's Fort Trail Park in Irving, TX #essays #writing

What if an outline weren't a chore, but the first draft on your path to fine writing?

Recently, my technical writing class was discussing outlining, when I was surprised to discover how many of my classmates hate the practice. But I shouldn't have been caught off guard, because I was in the same camp until only a few years ago.

Life before outlining

Sometimes you hear something enough that you can't help wondering if there might be something to it. And so was the case when I heard that the key to good writing is rewriting.

The idea that great writers rewrite goes against our romantic visions of the wordsmiths we admire. We like to picture our favorite authors as able to sit down at the typewriter or laptop, clang their fingers on the keys for a bit, and churn out great stories with no sweat or profanity.

But no, that's not how this writing thing works. You put some words on the page. You read over them and you scratch some out, and you move some around, and you fill in the holes in your prose until you hammer out something serviceable.

The wisdom about rewriting lodged itself deeper into my brain every time I heard it. And so began my acceptance that my writing needed a bit more work, opening the door for my eventual outlining practice.

Enter outlining

I owe giving outlining a shot to a bit of writer's block. I was stuck on a short story, unable to make the story's events fall into place. So I put aside what I had already written and started working on a barebones outlining. By taking a step backward, I was able to move forward and finish the story.

While I don't always start with an outline, I no longer avoid them as I once did. Outlines are the no-pressure way to start your writing project. You barf all your ideas into the outline, and you move things around or expand upon them. Or maybe you see that you don't have enough material for your project and you move on.

No matter the result, outlining is a great exercise.

An outline is a first draft

I now see an outline as a first draft—a bland, dry first draft. The outline is a first draft focused only on the skeleton, the crucial elements.

The next draft is where you can sprinkle on the flavor. Perhaps it helps to think of the second draft as the creative draft.

Projects require no set number of drafts, but it's a safe bet you'll need at least one more pass for spelling, grammar, and general sense making. So that puts you at three drafts, with the outlining being the first.

What all can I outline?

What all does outlining work for? So many projects, including:

  • Novels.
  • Short stories.
  • Blog posts.
  • Work emails.

Basically, any project that benefits from clear communication is a great candidate for an outline.

“The more things change, the more they stay the same.”

November 10, 2021 entry of The Daily Stoic November 10, 2021 entry of The Daily Stoic

November 9, 2021 entry of The Daily Stoic November 9, 2021 entry of The Daily Stoic

#stoicism

A reminder from today's entry from The Daily Stoic: Change is the only constant.

I'm happy to see Trainspotting by Irvine Welsh on display at my local library, but it feels a bit out of place.

A display at my local library A display at my local library

#photoblog

Looks like somebody judged a book by its cover...

My Oakland Raiders Khalil Mack jersey and my son's Derek Carr jersey My Oakland Raiders Khalil Mack jersey and my son's Derek Carr jersey

#essays #parenting #racket

These days, one of my favorite activities with my son is to head out to the backyard and throw the pigskin. We usually start with playing a simple game of catch and then we progress to him running routes with me playing out my fantasy of being the elite pocket passer.

I never got the chance to play quarterback. My school was too small to field a football team. What little I know about the game I learned from watching on TV and playing Madden and NCAA Football back when that was still a thing. But I've done my best to teach him some of the basics: the slant route, the curl route, the fly route. And I'm trying to get him to learn the concepts of sister routes: The in route is the sister to the out route, the corner route is the sister to the post route, and so on.

If my son ever plays organized football, he'll likely need at least three months to unlearn all that I've taught him wrong. But this is one case in which the point isn't to teach him what's right. The point is simply to teach him when he's at an age where he wants a certain type of mentorship. The point is that we're spending time together, creating our own version of the game that only we play.

You don't always have to teach kids right—sometimes you just have to teach them.


Listen on Racket: https://racket.com/jakelacaze/rGr4A

#technicalwriting #uxdesign

The following is from a discussion prompt for the class Usability and User-Centered Design, part of my technical writing certificate program via Oregon State University. I thought it was worth turning into a blog post.


For a couple months or so, I've been testing the Racket app via TestFlight on iOS. This is a short-form audio app (The founders often refer to it as the audio version of TikTok) that is finding its identity. As that identity changes, so does the UX. The branding (name, logo, colors) is the only thing that has been consistent over my testing.

The app has started to come together better and become more consistent as the team has latched onto an identity. This aspect is something that sometimes gets lost in the development of apps and sites: What is the identity of this service? What do we want people to feel? Also, how does our marketing affect our design?

Seth Godin often writes about how marketing is no longer isolated to one department. Now, every department of your company has a hand in marketing. Every part of your app/site/service is part of your marketing. This is something I wish more companies kept in mind. I go crazy when companies tell us they care about users and customers yet have horrible apps and sites that were obviously not developed with humans in mind.

Also, how does your company respond to criticism of its design? These days, I try to let companies know when I find errors on their sites or apps. For one, it's good practice for technical writing and UX design. But also, I'm trying to pay it forward because as someone who's dabbled in design, I know how easy it is to overlook little things when you're trying to juggle so much. I feel a deeper connection to a company when it responds and acknowledges my complaints, and maybe even makes the appropriate changes.

Enter your email to subscribe to updates.