情報を表現するときのポイント

Transcript

1. 情報を表現するときのポイント 2024-05-16 / 第112回社内勉強会 onozaty 1
2. 情報を表現するときのポイント Issueやチケット、チャットなど、情報を書いて伝える場面がたくさんあります。 情報を表現するときのポイントについて、3つほど紹介したいと思います。 2
3. ポイント 1. 記法を使いこなす 2. 文章で表現しづらいものは画像を使う 3. 画像でも表現しづらいものは、アニメーションをつかう 3
4. 1. 記法を使いこなす 4
5. 1. 記法を使いこなす テキストで書くようなものには、様々な記法が用意されています。 これを使うことで、単純な文章として書くより、表現力をあげることができます。 記法として良く使われるのはMarkdownです。 Markdown記法の中で、さらに(個人的に)頻繁に使うと思うものを紹介します。 5
6. Markdown - 見出し 入力 # 見出し1 ## 見出し2 ### 見出し3 表示 見出し1 見出し2 見出し3 6
7. Markdown - リスト 入力 - リスト1 - リスト1-1 - リスト1-1-1 ちゃんと折り返す - リスト1-2 - リスト2 - リスト3 表示 リスト1 リスト1-1 リスト1-1-1 ちゃんと折り 返す リスト1-2 リスト2 リスト3 リストの記号は - だけでなく、 * や + でもOKです。 7
8. Markdown - 番号付きリスト 入力 1. リスト1 1. リスト1-1 1. リスト1-1-1 ちゃんと折り返す 2. リスト1-2 2. リスト2 3. リスト3 表示 1. リスト1 i. リスト1-1 a. リスト1-1-1 ちゃんと折り 返す ii. リスト1-2 2. リスト2 3. リスト3 リストの数字は最初の数字からの連番になります。 なので、全部同じ数字でも問題ありません。(全部 1. でも同じ表示になる) 8
9. Markdown - コード(ブロック) 入力 ```java public static void main(String[] args) { System.out.println("Hello, world."); } ``` 表示 public static void main(String[] args) { System.out.println("Hello, world."); } ``` の後に識別子となる情報(プログラミング言語名など)を指定することで、シンタ ックスハイライトでの表示となって読みやすくなります。 9
10. Markdown - コード(ブロック) 何かの差を表現したい時には、 diff を使うとわかりやすいです。 (たとえばコードの修正イメージ) 入力 ```diff public static void main(String[] args) { - System.out.println("Hello, world."); + System.out.println("こんにちは世界！"); } ``` 表示 public static void main(String[] args) { - System.out.println("Hello, world."); + System.out.println("こんにちは世界！"); } 10
11. Markdown - コード(インライン) 入力 `String`の`replace`メソッドを使う。 表示 String の replace メソッドを使う。 11
12. Markdown - リンク 入力 [Google](https://www.google.com) https://www.google.com 表示 Google https://www.google.com サイトのタイトルを表示名にしたいような場合、上記のようなものを手で書くのは面 倒です。 ブラウザの拡張で、現在表示しているページのリンクをMarkdown形式で作ってくれる ようなツールがたくさんありますので、それを使うと良いでしょう。 Create Link - Chrome Web Store 12
13. Markdown - 引用 入力 > ここが引用です。 この行は引用じゃないです。 表示 ここが引用です。 この行は引用じゃないです。 13
14. Markdown - 太字、取り消し線 入力 太字で**強調**できます。 ~~採り消し~~取り消し線で修正を表せます。 表示 太字で強調できます。 採り消し取り消し線で修正を表せます。 14
15. 1. 記法を使いこなす Markdownでも、そのツール特有の記法があったりします。 ツール特有の情報(Issueやチケット、Wikiなど)へのリンク メンション など... 一度そのツールでの記法をざっと確認してみると、便利な使い方があるかもしれませ ん。(あとは、既に書いているものをみてみるとか) たいてい入力欄の近くに記法に関するヘルプのリンクがあると思いますので、そこか ら参照してみてください。 15
16. 2. 文章で表現しづらいものは画像を使う 16
17. 2. 文章で表現しづらいものは画像を使う 文章で説明するより、画像で見た方がすぐわかるようなことも多々あります。 たとえばWebアプリケーションで表示崩れがあった場合に、文章で説明するのは難し いですが、ブラウザで表示した際のスクリーンショット画像があれば、それだけで伝 わります。 ただし、スクリーンショットが楽ということで、なんでもかんでも画像にしてしまう のは控えましょう。 たとえば、ログやエラーメッセージのような、文字情報として有用なものを画像にし てしまうと、後から文字として検索できなくなってしまいます。 17
18. Snipping Tool / 切り取り＆スケッチ Windowsならば標準で入っている Snipping Tool / 切り取り＆スケッチ で簡単にキャプ チャできます。 Snipping Tool を使ってスクリーン ショットをキャプチャする - Microsoft サポー ト 18
19. Snipping Tool / 切り取り＆スケッチ ※アニメーションGIFなので環境によっては動きません 19
20. Screenpresso Snipping Tool / 切り取り＆スケッチ でもちょっとした加工ができますが、私は枠線や テキストを入れたくて、ScreenpressoのPro版を購入して使っています。 Screenpresso：Windows用の究極のスクリーンキャプチャツール Screenpresso の無償版でも枠線やテキストを入れられるので、Snipping Toolで編集弱 いな、、と思ったらぜひお試しください。おすすめです。 20
21. Screenpresso ※アニメーションGIFなので環境によっては動きません 21
22. 3. 画像でも表現しづらいものは、アニメーションをつかう 22
23. 3. 画像でも表現しづらいものは、アニメーションをつかう 動きがあるようなものは、画像ではなくアニメーションにすると、さらに伝わりやす くなります。 また、伝える方としても、画像をたくさん張り付けたり、文章で動きを補足したりな どする必要もなく、手間を減らすことができます。 23
24. ScreenToGif Windows だと ScreenToGif というOSSのソフトがとても便利です。 ScreenToGif これを使うと、とても簡単に、画面上の操作を撮影して、アニメーションGIFとして保 存できます。 24
25. ScreenToGif ※アニメーションGIFなので環境によっては動きません 25
26. おわり 26