This is a bit of a "guide" with recommendations on how to write when you're trying to teach someone something on Tofugu or WaniKani. The most common place where the contents of this guide will apply is in the Tofugu Blog, especially in the Japanese Language and Japanese Grammar sections, but much of what is written here can apply wherever explanatory writing is being done.

✍🏾 The Writing Itself

Far be it from me to tell you how to write. That's not the purpose here. Everything here is pretty general, and should still allow your personal style to shine through your writing.

Using First Person

When writing your article, you should use first person most of the time (see exceptions below). Using "we" everywhere turns us into a faceless company. But, we're a bunch of people, and I want everyone to get credit for that. "We" don't think xyz about some linguistic theory, "You" think that. So, use "I," tell people your opinion, and make it your opinion, not Tofugu's.

Using Second Person

Whenever possible, use "you" when teaching, whether that's teaching the reader how a grammar point works or teaching the user how our product works. Using both "I" and "you" makes our writing more personable and personal. We want the reader to know what they will be able to do if they study xyz: "You will be able to read a menu after completing this course" or "You might want to check out this temple."

Using Third Person

Go ahead and refer to your colleagues by name. Talk about "My Ossan Rental article" not "Tofugu's Ossan Rental article." Refer to "Kanae's article on あなた," not "our article on あなた." Praise "Aya's art," not "Tofugu's art."

That said, there are times where "Tofugu" or "WaniKani" should be mentioned. The most obvious example is when you're referring to the product itself. "WaniKani's SRS system" or "Tofugu's Grammar section." You should also use third person when referring to something "the team" did. You might say "Go read Tofugu's Learn Hiragana guide," for example, or say "We wrote a guide to learn hiragana."

De-Obfuscate Simplify Your Writing

We often have to explain complicated stuff (more on how to make things less complicated below). Don't make your writing so complicated that it makes it even more difficult for the reader to learn or understand what it is you're explaining. Use simple words. Avoid jargon. Figure out how to say it a different way. Remove unnecessary clauses, adjectives, verbs, and adverbs. They make what you wrote more difficult to read.

What are you trying to say?

You need to be clear, from the start, what the reader will get out of it if they read your article. This is what we refer to as the "thesis" of the article, though it's quite a bit less formal than an academic paper (though no less difficult to figure out). Your job here is to state what you want to say with this article and why the reader should bother reading it, and do it in a way that's enticing, humorous, and/or unexpected. At the same time, your thesis shouldn't overpromise, exaggerate, or overvalue. Be honest with the reader. Not everything is amazing. Not everything is shocking. Not everything is astounding. But, your thesis should be clear in why it's useful, and ideally this is stated in a clever way. This takes craft.

Thesis ← h2s ← Sentences

So you have your thesis, now what? Our articles tend to be broken up into a series of headers—h2s—inside of which there are paragraphs and sentences. Each h2 section should have a point, a point that supports and adds to the article's thesis. You always have to ask, "why is this section important and does it have a point?"

But, it doesn't end there. h2 sections have paragraphs, and each of these paragraphs should support its section's point/purpose as well as the overall thesis. Each paragraph brings more information, more complexity, and more depth.

Let's go even deeper. Time to look at the last sentence of each paragraph. Does it form a bridge between the paragraph it's in and the paragraph ahead? Does it make the reader want to keep reading? Does it support the thesis, whether it be the section's thesis, or overall?

As you write each h2 section, each paragraph, and even each sentence, it is important to ask: "Did I say what I wanted to say?" If not, it's time to revise.