はじめに
この記事は、アウトプットの心構え Advent Calendar 2023 の 6 日目の記事になります。
この記事の立ち位置
私は Qiita で記事を編集することをよくしています。
そこで、Qiita を編集していてよく遭遇する出来事とかをまとめていこうかなと思いました。
記事を書き始めたての人にはぜひ、実践していただきたいものになっています。
記事を編集する理由
技術記事を含めて、ドキュメントというのはソフトウェアととても似ています。
以下は、ドキュメントとソフトウェアの類似点です。
古くなる
ソフトウェアは、定期的な改善や更新をしなければ時代遅れになる傾向があります。
技術記事もこれと同じで、新しい情報や方法に合わせて更新しないと、やがて陳腐化します。
たとえば、アプリの開発で用いられるライブラリやプログラミング言語は、常に進化しています。これらを最新の状態に保たないと、ソフトウェアは古くなってしまいます。
技術記事においても、紹介されるライブラリや手法が進化し続けるため、記事を更新しなければ、やがて古くなり、役立たなくなるでしょう。
人によって「読みやすい」 or 「読みにくい」が発生する
ソフトウェア開発における美しいコードと同様に、技術記事にも美しい文章が存在します。
また、ソフトウェアでは、不適切なコメントや 冗長な print メソッドが多いと、可読性を下げる原因にもなります。
技術記事においても、文章のみならず以下の要素が重要です。
- 画像：アプリのスクリーンショットなど
- コードブロック：サンプルコードの紹介など
- URL：URL の埋め込みなど
これらの要素が記事の内容と調査していないと、文章の美しさや読みやすさが損なわれます。
ソフトウェアと技術記事は、それぞれの形で美しさを追求し、最適な構成で情報を伝える必要があります。
以上のように、ソフトウェアと技術記事はとても似ています。
そのため、ソフトウェアを定期的に編集・更新するのと同様に、技術記事も編集・更新する必要があります。
古い記事・読みにくい記事と出会った場合
では、古い記事・読みにくいと出会った場合はどうすべきでしょうか？
- 見なかったことにしてそっとブラウザバックする
- 「古い・見にくい」と編集案を出して優しくコメント・Twitter (現 X) にシェアする
上記の方法も良いですが、読者の皆様はぜひ修正するという方法を検討していただきたいです。
あなたの貢献によって、多くのエンジニアが救われます。
本題：記事を編集して遭遇する出来事
さて、ここから本題です。
以下では、実際に私が遭遇した出来事を書いていきます。
画像のサイズが大きい or 小さい
アプリケーションの画像サイズが大きかったり、小さかったりして「うお、見ずら💦」となることはよくあります。
例えば、以下のようにいきなり大きな画像を貼られると。
とても読みづらいです。
これがスマートフォンなどの小さい画面だとさらに読みづらいです。
といった具合です。
逆に小さすぎると、肝心の画像が見にくく、画像を貼った意味を見出せません。
解決法
Qiita や GitHub では、ローカルからドラック & ドロップすると以下のように出力されます。
ここで、以下のように編集するとサイズを変更できます。
- 
+ <img src="https://Sample.png" width=50%>
HTML を触る人ならこの書き方はよく見ます。
width は width=300 にしても良いです。
数値は画像のサイズによって変更してください。
これで、画像の大きさを変更できるようになり、「うお、見ずら💦」と感じる人は少なくなりました。
コードブロックの言語指定
サンプルコードを貼っていただけるのはとてもありがたいです。
しかし、言語指定されていないと非常に読みにくいものになってしまいます。
1 行や 2 行ならまだ良いのですが、10 行以上だと読むのが辛くなります。
例えば、以下のようなコード。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
}
}
#Preview {
ContentView()
}
これは Xcode で SwiftUI 製の iOS アプリを作成すると最初に書かれているコードになります。
iOS エンジニアであれば容易に読めますが、Swift に読み慣れていない人には厳しいです。
解決法
```swift とつけ、言語を指定することで以下のようにハイライトをつけることができます。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
}
}
#Preview {
ContentView()
}
これで、サンプルコードを読みやすくなりました。
コードブロックのファイル指定
先ほどのサンプルコードに言語を指定することでハイライトをつけることができました。
しかし、技術記事によっては、特定のファイルにコードを追記してほしい場合があります。
先ほど登場した以下のサンプルコードの場合、どこのファイルにあれば良いのでしょうか？
このままだとよくわかりません。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
}
}
#Preview {
ContentView()
}
解決法
```swift:content.swift と書いてあげるとファイル名を表示してくれます。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
}
}
#Preview {
ContentView()
}
コードブロックの差分
コードブロックに言語指定、ファイル指定ができました。
これでも十分読みやすい記事になりましたが、以下のコードのように編集を加えてみます。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, Qiita!")
}
.padding()
}
}
#Preview{
ContentView()
}
さて、このサンプルコートは 2 箇所変更が加えてあります。
この状態だと、どこを変更したかわかりにくいです。
解決法
ここで、言語指定した際に ```swift としました。これを ```diff_swift に変更します。
つまり、以下のコードでは、```diff_swift:Content.swift としました。
さらに、変更前のコードの前に - を、変更後のコードに + をすると以下のように変更箇所をわかりやすく表示してくれます。
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
- Text("Hello, world!")
+ Text("Hello, Qiita!")
}
.padding()
}
}
- #Preview {
+ #Preview{
ContentView()
}
これによって、変更箇所を表示できました。
URL の埋め込み
URL の埋め込みは非常に便利で Qiita 以外にも Slack や Notion など様々な場所で使われています。
例えば、以下のように記事を書いたとします。
先日、GitHub が公開している Open Source Guides にコントリビューション ( 貢献 ) してきました。Open Source Guides については[こちら](https://opensource.guide/)を参照してください。
先日、GitHub が公開している Open Source Guides にコントリビューション ( 貢献 ) してきました。Open Source Guides についてはこちらを参照してください。
悪くないですが、わざわざ「こちらを参照してください。」と書くと文が冗長になります。
解決法
そのため、以下のように参照してほしい単語に URL を埋め込むと文がまとまります。
先日、GitHub が公開している [Open Source Guides](https://opensource.guide/) にコントリビューション ( 貢献 ) してきました。
先日、GitHub が公開している Open Source Guides にコントリビューション ( 貢献 ) してきました。
この書き方は、OSSAdvent Calendar 2023 1 日目の投稿で実践しています。
別の解決法
他にも、Document 自体を参照する場合は、以下のように書くと「どのタイトル」で「どこから引用されたか」がわかるのでオススメです。
[8歳娘「パパ、なんでそんなにいいねを欲しがるの？」 - Qiita](https://qiita.com/Yametaro/items/742dd0e5aab6b04450d1)
最後に
以上のように、少しの工夫で文章を読みやすくすることができます。
これらのことを参考に記事を作成・修正して、エンジニア界を盛り上げていきましょう！