テクニカルライティングの基本テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://spe…
開発ドキュメントの書き方！9つのコツ【エンジニア】
文章を書く前にやることよい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。 このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。 開発ドキュメントを書く前に決めるべき3つのこと【企画編】開発ドキュメントにおけるアウトラインの書き方開発ドキュメントの書き方企画とアウトラインの作成が終わったら、実際に文章を書いていきます。文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。 一文を短く切る結論を先に述べる指示語を使わない主語を明確にする、述語との距離を近づけるひらく・閉じるを統一する再現条件を示す前提を揃える見出しや箇条書き、表などを適切に用いる読者に伝わる用語を使うひとつずつ説明し
デジタル情報を整理するための完璧なシステム「PARAメソッド」とは？
仕事や趣味の資料・タスクなどさまざまなデジタル情報を扱う人は、どのアプリでどのプロジェクトを管理し、どのフォルダ内の資料が何に用いるものなのか、また今はどれくらいの進行度合で何を目標としているのか、整理に苦労した経験も多いはず。そんなデジタルプロジェクトを整理するために、テクノロジーを使用して労働者の生産性が向上することを目標に掲げるForteLabsが提唱した方法論が「PARAメソッド」です。 The PARA Method: A Universal System for Organizing Digital Information - Forte Labs https://fortelabs.co/blog/para/ ForteLabsの創設者である生産性に関する専門家のティアゴ・フォルテ氏は、「人間中心の仕事の未来」を掲げてテクノロジーで知的労働者の生産性を向上したり、アイデア管理
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
「システム運用アンチパターン」を一読したので、その要点（特に薦めたい感想5点） - Qiita
システム運用アンチパターン ―エンジニアがDevOpsで解決する組織・自動化・コミュニケーション | Jeffery D. Smith, 田中 裕一 |本 | 通販 | Amazon エンジニアがDevOpsで解決する組織・自動化・コミュニケーション。早速お薦めしたく書いています。読書感想文です。 感想5点 良いぞ。周りに薦めたい 百聞一見。目次だけでも: https://www.oreilly.co.jp/books/9784873119847/#toc 特に自分にとって良かったのは以下 9章 せっかくのインシデントを無駄にする 10章 情報のため込み：ブレントだけが知っている だが、一番スゴイのは11章かもしれない 「文化を変えようと思うのであれば、文化がどのように共有されているかを理解すること」 コロナ以前は 議事録 会議 机横での雑談 飲み会 タバコなどなどあったが コロナ以降、リ
うまい文章をラクに書くための「たったこれだけ」の工夫5選。 - STUDY HACKER（スタディーハッカー）｜社会人の勉強法＆英語学習
「文章をうまく書くには、やっぱり訓練が必要……？ でも面倒なことはしたくない」 「難しいことや特別なことをしなくても、文章力がアップする方法を知りたい！」 このような人に向けて、うまい文章をラクに書くための “ちょっとしたコツ” を5つご紹介します。メール、チャット、報告書など、あらゆるビジネスシーンで使えるものを集めました。誰でも簡単に実践できますから、読んだら “即” 使ってみましょう。 1. 一文を「短くする」だけ 仕事の情報は複雑で、文章にするとどうしても込み入ってしまうもの。もっとスマートに書きたいのに……と思うなら、「一文を短くするだけ」で効果的です。 数々のヒット作を生み出すコピーライターで、“端的に文章を書くプロ” である橋口幸生氏。同氏は、読みやすい文章を書くには、一文を40～60字以内にまで短くするとよいと言います。 これは、一文に書く内容をひとつに絞ると実現できるとの
Dockerfile のベスト・プラクティス — Docker-docs-ja 19.03 ドキュメント
このドキュメントは、効率的なイメージ構築のために推奨するベストプラクティスを扱います。 Docker は Dockerfile に書かれた命令を読み込み、自動的にイメージを構築します。 Dockerfile はイメージを構築するために必要な全ての命令を、順番通りに記述したテキストファイルです。 Dockerfile は特定の書式と命令群に忠実であり、それらは Dockerfile リファレンス で確認できます。 Dockerfile の命令に相当する読み込み専用のレイヤによって、 Docker イメージは構成されます。それぞれのレイヤは直前のレイヤから変更した差分であり、これらのレイヤは積み重なっています。次の Dockerfile を見ましょう。 命令ごとに１つのレイヤを作成します。 FROM は ubuntu:18.04 の Docker イメージからレイヤを作成 COPY は現在のデ
GitHub Actions で簡単にバージョン番号付きリリースとリリースノートを作成する方法
対象読者判定フロー 以下の質問にはいかいいえで答えてください。 Q1: GitHub を使用していますか？ はいの方→次の質問に進んでください。 いいえの方→対象外です。すみません。 Q2: ソースコードなどの変更は全てプルリクエストで行って（＝master/main 直コミットはしていない（多少ならOK））いますか？ はいの方→次の質問に進んでください。 いいえの方→まずはプルリクエストベースの開発に切り替えてみてはいかがでしょう？ その後で続きを読んでください。 Q3: リリースノートをちゃんと書いていますか？ はいの方→基本的に対象外です。継続して書いていって下さい。楽をしたいと思ってる場合は続きを読んでください。 いいえの方→あなたは対象読者です！ この記事を読んで、お手軽自動生成でも良いのでリリースノートを作成しましょう！ はじめに 公開しているソフトウエアにバージョン番号を付け
プロダクトマネージャーの仕事を10倍快適にするNotion活用法【テンプレート公開】｜Shin
最近は仕事をするとき必ずNotionを触っていますので、仕事をする=Notionを使う、と言っても過言ではありません。Notionの素晴らしい点は、私のように複数社で顧問をしていても、必要な業務によってカスタマイズができることです。 日々Notionを使う中で「プロダクトマネージャーが圧倒的に仕事しやすくなるテンプレートを作りたい！」と思ったのが始まりです。そんな中いろいろ探してみたところ、Notionのテンプレート自体はすでに色々なものがありますが、現実問題としてToo much（情報が多すぎる）ものもあれば、逆に情報が足りないものもあり最適解がありませんでした。 そこで、プロのプロダクトマネージャーとしてこれを使っておけば間違いない！というものをキュレーションして整理しました。そのテンプレートの使い方を解説します。 ※テンプレートはページ下部からご利用になれます プロダクトマネージャー
プロダクト開発でドキュメントを書かないとどうなるか
Agile Manifestoには以下のように書いてあります。 動作するソフトウエアは包括的なドキュメントにまさる ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよ
継続的ドキュメンテーション: Github DiscussionsとADRのすすめ - LIFULL Creators Blog
こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。 会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど... LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。 多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。 LIFULLの開発現場にもこの
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
