手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce

新卒で社会人になって以来、ソフトウェアのエンジニアをかれこれ10年近くやっています。そんな私が、新卒で入った会社の最初の配属先で、上司の上司に教えられた報告の書き方について紹介します。 報告には意味を書くその人は「報告には意味を書くこと。」と常々言っていました。「ただ単にやったこと、起こったことを書いたものは"日記"。その意味を書かないとダメ。日記が許されるのは新人のうちだけ」だと。 ダメな例：「○○の設計はxx日に完了。現在は実装中。」 こういう週報を書くと、「これは日記だよ」と指摘されます。設計がxx日に完了したことが、チームやプロジェクトにとってどういう意味をもつのかが書かれていないからです。この報告は、例えば以下の様に改善できます。 改善した例：「○○の設計は、予定通りにxx日に完了。・・・」 これならば、「設計がxx日に完了 → これは予定通りである。順調である。」という意味が盛

こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。 jasperapp/jasper/ARCHITECTURE.md ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。 https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html https://github.com/rust-analyzer/ru

大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体

UXライティングとは何か UXライティングとは、ユーザーがデジタルサービスを操作する際に必要となるテキストを書く技術です。例えば、登録時のスタートガイド、利用の流れコンテンツ、タイトル、ボタン、画面上の説明文、エラーメッセージ、通知などの言葉がUXライティングの手法に則って書かれます。サービスの中にある言葉に対して「意味が通じればいい」という思想で書くのではなく、「ユーザーがサービスを通じて体験する一連の経験を設計する」という思想で書くのがUXライティングです。 UXライティングに求められる技術とは UXライティングには、分かりやすく書く技術と、人間らしく書く技術が必要です。この二つの技術が同居することによって、ユーザーの体験を支援することができます。 分かりやすく書く技術 UXライティングの手法に則ってテキストを書く際に求められるのは、「ユーザーの気持ちに沿った文章を書く」という抽象的な

Your space for notes, tasks, and big ideasTry Craft Free

After several intense months of work on such a significant change, the day is finally upon us: MDN Web Docs’ new platform (codenamed Yari) is finally launched! Between November 2 and December 14, we ran a beta period in which a number of our fabulous community members tested out the new platform, submitted content changes, allowed us to try out the new contribution workflow, and suggested improvem

こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼

リモートワーク ハンドブック #このサイトについて #NTTコミュニケーションズ社内で製作したリモートワークハンドブックの内容を、 より一般化して広く公開するものです。 ソースコード #本書のソースコードは https://github.com/nttcom/remote-work-handbook で公開しています。 ライセンス #NTT Communications Corporation 作『リモートワーク ハンドブック』は クリエイティブ・コモンズ 表示 - 非営利 - 継承 4.0 国際 ライセンス で提供されています。 関連ハンドブック #オンボーディングに特化した オンボーディング ハンドブック や、チームビルディングのプラクティスをまとめたチームビルディングハンドブックも参照ください。 読み始める #こちらから本編に進めます。 本書について

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介していま

こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。今日は「テクニカルライター」というお仕事と、LINEにあるテクニカルライティングの専門チームについてお話しします。 テクニカルライターという職種があります テクニカルライターって何をしてるの？何を書くの？ ドキュメントはどうやって書いてるの？ どんなメンバーで仕事をしてるの？ ドキュメントを書く以外にこんなこともしているよ でもドキュメントを書くだけだと技術力が下がらない？ どんな人がテクニカルライターに向いてるの？ テクニカルライターという職種があります 私はもともとウェブ制作会社のインフラエンジニアでした。とある技術書を書いたことをきっかけに「テクニカルライターとして一緒に働きませんか？」と声をかけてもらい、LINEへ転職するに至ったのですが、実はお誘いをい

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

サービシンクの名村が25年に渡るWeb制作のプロジェクトマネジメントで「テキストで情報を伝える」上で認識齟齬に至る点を洗い出した「誰がどう見てもそうとしか受け取れない文書術」のセミナースライドの2020年3月29日公開版です。 Web制作・システム開発に関わる人以外には事例等が分かりにくいかもしれませ…

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

This post highlights some of the key components of good documentation, and goes through some of the steps you could take to improve the way you document your code. Documentation is one of the most important and under-rated aspects of any library or open-source project. If you are writing code that will be used by someone other than yourself, it needs to be documented. Period. After using many libr

LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog はじめにテクニカルライター（technical writer）という言葉を聞くと、ほとんど「ライター」という単語だけ見て「文章を書く人」と思いがちです。もちろん間違いではありません。しかし、実際にキーボードを叩いて文章を書く仕事は、テクニカルライター業務のほんの一部です。1日にどれくらい文章を書くか測定したことはないですが、テクニカルライターのトム・ジョンソン（Tom Johnson）によると、仕事をする時間の約10%が文章を書く時間だそうです。 では、その他の時間には何をしているのでしょうか。これもトム・ジョンソンによると、開発者のインタビュー、ほかの人が書いたドキュメントのレビュー、アプリの動作を録画するためにiPhone