ど素人が Markdown とお友達になるまで

こんにちは。株式会社フィックスポイントのよしだです。

今回は、当ブログ史上初となる非エンジニアの記事です!

普段の記事では、エンジニアのみなさんが勉強会にて発表した内容をまとめていますが、今回は満を持して(?)私自身の勉強会発表のお話をさせていただきます。

いつもよりはライトな内容ですので、軽い気持ちで読んでいただけると思います😌

はじめに

今回の記事では、表題にもある通り「他業界からIT業界へ転職したての知識皆無な人間が、Markdown 記法をどのように習得していったか」についてお話ししていきます。

そもそも、なぜ私が Markdown 記法を習得しなければならなかったかと言うと、当社製品のマニュアルを Web 化したかったためです。

Web 化の主な狙いとしては、「製品マニュアルの体裁を統一したい」「GitHub 上で管理して履歴を分かりやすくしたい」といったものがありました。

実際の製品マニュアルは下記の通りですので、興味のある方は覗いてみてください!(2022/05/23現在、公開済みのもの)

製品について気になった方は、こちらを見てみてくださいね!

support.kompira.jp

それでは、私の山あり 谷ありな道のりを追っていきましょう💪

出会い

私が Markdown と出会ったのは、入社から一ヶ月ほどした 2021/12/7 のことでした。

この時は、「Markdown っていう方法でマニュアルを書くらしい」程度の認識だったため、前職でも使用していた Word や PPT とさほど変わらないだろうと思っていました。
認識甘すぎますよね😇

初めて VScode 上にてお会いした時の印象は…
「えっ…編集リボンがない!!!」
でした。

とにかく当時は WYSIWYG ではない操作に混乱してしまい、「ちゃんとマニュアルを完成させられるのだろうか…」と不安になりました。

大失敗

混乱はしたものの、ネットで検索すれば Qiita の記事を中心に参考となるものがあったため、それらを頼りに書き進めて行きました。

そして、自分としては最初の印象ほど苦労せず意外と書けている印象だったので、できたものを早速エンジニアの方に見ていただきました。

すると…

全然できてませんでした。

本当に全然できていなかったので、私の一番最初のコミットから一部お見せします🙃

今見ると本当にできていないことがよく分かります…箇条書きができていなかったり、やたらと太字が多かったり、コードブロックも作れていないなどなど…

ひとしきりご指摘をいただいた後、あるアドバイスをいただきました。

Markdown では、デザインをしてはいけないんです」

最初聞いた時はなにを言っているのかピンときませんでしたが、説明をしていただくうちに私の中での Markdown の認識に変化がありました。

Markdown はあくまで構造的に書くべきであり、見え方に注目して書くべきではない。

前述の通り、私は今まで Word や PPT を中心に文章を書いていたため、見た目に囚われてドキュメントの構成を行っていました。

しかし、Markdown の場合は見た目を意識して書くのではなく、記法上の構造に注意して書く必要があることに気付かされたのです。

たしかに Markdown はあくまでも「記法」なので、Markdown 上の書き方に注目して書くべき、という理論はとても腑に落ちました。

情報収集

さて、理論は理解できましたが、具体的に「構造的に書く」とはどのように実践すればよいのでしょうか。

自分だけでは経験的に分からない部分が多いため、なかなかイメージが湧きませんでした。

そこで目をつけたのが、Docbase でした。

社内に公開されているあらゆる Docbase の記事も Markdown 記法じゃないか!と気付き、先人たちの記事を参考にすることにしました。

具体的な使用例を見ることにより、見出しや箇条書きの活用方法や逆にあまり使われないものなど、実際の使い方が分かってきました。

実践

Markdown のポイントと使い方のイメージは掴めたため、それからはただただ実践し慣れていきました。

分からないことが出た時は、

  1. ググる
  2. Slack に書き込む!
  3. Gather で聞いてみる!

というようにして乗り切りました😊

「2. Slack に書き込む」について補足すると、弊社では社員が Slack 上に "#times-name" という各自のチャンネルを持っており、そこに好きなように書き込めるようになっています。

仕事に関する疑問や思考をひたすら書き込んだり、Twitter のように思ったことを雑談としてつぶやいたりすることもできます。

それを利用して、Markdown についてなにか詰まったことがあったら素朴な疑問として書き込むようにしていました。

書き込みを見た人は適宜教えてくれたり助け舟を出してくださるので、とてもありがたい文化だなあと実感しました。

ちょうど Markdown の件でいい例があったため、載せておきますね。

「3. Gather で聞いてみる」についても同様で、Gather にて気軽に質問を投げ合えるのも非常にいい環境だと感じています。フルリモートの寂しさも紛れますしね🌻

当ブログの一番最初の記事でもご紹介していますので、興味のある方はこちらをご覧ください✨

blog.fixpoint.co.jp

まとめ

以上が、ど素人が Markdown を習得するまでの流れでした。

Markdown を身につけるにあたって、改めて私の中で「なにかを学習する際に大事な習得の流れ」があると身に沁みて感じたので、記載させていただきます😌

  1. その分野に詳しい人に最初のポイントを説明してもらう
  2. ポイントが分かったら、先人たちのものを真似てみる
  3. 分からなければ、即聞く
  4. あとは慣れ

やはり人間と同様、Markdown さんも一気に距離を詰めてお友達になるのは難しかったです😅

そのため、最初に人間性(ポイント)を掴んで、徐々に仲良くなって(慣れて)行くという作業が必要だと痛感しました。

これについては今回の Markdown に限られたことではなく、色々な分野に共通することかと思います。

みなさんもなにかを習得しなければならない時には、思い出していただければ幸いです♪

おまけ

「はじめに」の部分で、マニュアルを Web 化する理由として「GitHub 上で管理して履歴を分かりやすくしたい」と挙げていたのを覚えていますでしょうか?

Markdown とも格闘した私でしたが、GitHub にも大分苦労して作業を進めていました😇

かなり苦戦し時間はかかったものの、多くのエンジニアのみなさんにサポートを受けて、なんとか今ではコミットも綺麗に出せるようになりました。

せっかくなので、そのビフォーアフターも記載しておきます!

違いが一目瞭然ですね😂

最初は使い勝手がよく分かっていないのもあり、コミットメッセージが全部同じになってしまっています。

回数を重ねていくうちに、コミットをきちんと分けることやコミットメッセージを具体的にすることなどを意識するようになり、他の方が見ても分かりやすい履歴となったのではないかと思います。

参加者の反応

参加者からは、最後のおまけのところでたくさんお褒めの言葉をいただきました😊
私が思ってる以上にすごいことだったようです。笑

コミット履歴を綺麗にすることの大切さが伝わってきますね。

私としては、やはり Slack 上からコメントをリアルタイムで確認できると発表者側の気持ちも楽に発表できるので、これもいいシステムだと実感しました。

最後に

今回は、非エンジニアである筆者がどのように Markdown を習得したかの道のりについてお話ししました。

まとめ部分にもあるように、様々な学びの分野にて応用できる経験ができたと感じています!

今後もなにか機会があれば、非エンジニアの記事も執筆したいと思いますので、楽しみにしていてくださいね。






株式会社フィックスポイントでは、一緒に働いてくれるメンバーを募集しています!

詳細は、こちらをご覧ください。