テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter:https://twitter.com/naoh_nak 2022年版(初版):https://sp…
![テクニカルライティングの基本 2023年版](https://cdn-ak-scissors.b.st-hatena.com/image/square/f73a4e161eba2f2c70fcf08899c88c585382ddaf/height=288;version=1;width=512/https%3A%2F%2Ffiles.speakerdeck.com%2Fpresentations%2F6d29f16691a1401495d18b7fea44b85b%2Fslide_0.jpg%3F26087129)
Real World HTTPでも紹介したネタですが、お仕事で受けている技術コンサル中に質問をいただいた時に、微妙に本で紹介した内容では少し足りなかったので、改めて整理のためにブログ記事にしてみました。次回、本が改訂されることがあればこのブログエントリーの内容も入れて加筆したいと思います。 Real World HTTPだとGoを使っていましたが、フロントとサーバーを同時にいじるので、本エントリーではNext.jsをサンプルに使います。Next.jsでプロジェクトを作って(npx create-next-app@latest –ts)、適当なプロジェクト名を入れてアプリケーションの雛形を作っておいてください。 Next.jsでは、1つのスクリプトファイルを作成すると、それがサーバーAPI(/pages/api以下)と、フロントの画面(/pages/以下のapi以外)になります。Next.j
AWS認定トレーニング講師の平野@おんせん県おおいたです。 さて、2021年に下記のような Well-Architected フレームワークのブログを書きました。 最近AWS Well-Architectedのドキュメントがアップデートされましたので、それに伴いブログも新しくリリースしました。 おもな変更点 ドキュメント構成の改善に対応 ドキュメント自体が読みやすくなりました(詳細は後述)。それに対応して、内容を変更しました。 新しい柱への対応 2021年12月に「持続可能性の柱」が追加されましたので、この新しい柱についての記事を追記しています。 尚、2022.1.9時点で日本語化されておりませんので ブログ内の見出しは、私の方で日本語訳したもの 各リンク先は英語ページ となっておりますので、ご了承ください。 はじめに AWS Well-Architected フレームワークとは AWSと
システム開発にドキュメントは欠かせません。ドキュメントが得意になれば活躍の幅が大いに広がりますよね。 この記事では、まず冒頭でドキュメントの作成に求められると思うことを整理した上で、そのスキル獲得に役立つと思われる記事や書籍を集めてみました。もちろん他にもあると思うので、もしお薦めのものがあれば是非コメントで教えて下さい 更新履歴 ・2021/04/16:文章術系にリンクを追加しました。 ・2020/11/28:文章術系にリンクを追加しました。 ・2020/07/24:文章術系にリンクを追加しました。 ・2020/05/24:文章術系にリンクを追加しました。 ・2020/05/14:スライドデザイン系にリンクを追加しました。 ・2020/04/29:スライドデザイン系にリンクを追加しました。 ・2020/04/17:文章術系にリンクを追加しました。 ・2020/04/12:関連するTwit
LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介していま
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が(たぶん) IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル(
このページについて この記事は、以前書いた「社内Wikiに情報を書くときに守ってほしい、たったひとつのルール」の続編です。前回は、個々のページをどう書くべきかという話をしましたが、今回は社内 Wiki 全体を信用できるものにする方法について考えます。 muziyoshiz.hatenablog.com 想定する環境 この記事は、ソフトウェア開発プロジェクトに関する Wiki が社内にあって、そこに各人がドキュメント(仕様書や手順書など)を書けるようになっている環境を想定しています。 私自身、ソフトウェア開発のときしか Wiki を使わないので、具体例もそのような環境に寄っています。ただ、ある程度は社内 Wiki 全般に通じる話かと思います。 ルール:「更新され続ける」ページと「更新されない」ページをはっきり分ける ここ1年ほど社内プロジェクトをいくつか渡り歩いていたのですが、個人的には、こ
はじめに こんにちは植木和樹@上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 (この記事を読むのにかかる時間の目安:5分) 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
概-1 ⓒ2023 NTT DOCOMO, INC. All Rights Reserved. 令 和 5 年 4 月 1 日 株式会社NTTドコモ 本書に記載の会社名・製品名・ロゴは各社の商標または登録商標です MVNO様向け卸携帯電話サービス概要のご説明資料 © 2008 NTT DOCOMO, INC. All rights reserved. ⓒ2023 NTT DOCOMO, INC. All Rights Reserved. 概-2 1.本資料について 本資料は、当社携帯電話回線を利用したMVNOとして電気通信サービスの提供をご検討されている 電気通信事業者様等(以下、「MVNO様」という)向けに、卸携帯電話サービス契約約款(以下、「卸約 款」という)にて公表しておりますMVNO様向け卸携帯電話サービス(卸Xiサービス及び卸5Gサービス )の標準プラン(以下、「標準プラン」とい
はじめまして! 株式会社 Aiming の土井です! エンジニアをやっております! 今回の開発者ブログでは、情報共有ツールとしての UML の活用方法について、現場での取り組みをご紹介させていただければと思います! 技術仕様書の“図” どうやって書いてますか? 株式会社 Aiming では、プロジェクトの Wiki やバグトラッキングに Redmine をメインに使っています。みなさんも既にご存知だったり、実際にバリバリ活用されていることとおもいます。 また、企画仕様書、技術仕様書などは Redmine の Wiki やエクセルに代表されるオフィススイート等を活用して作成しますが… 図の表現を求められるような仕様書を作る時に、どうやって作成しようか悩んだことはありませんか? 標準ペイントソフトで頑張って作成 オフィススイートに含まれる、ドローツールを使って図を作成、画像吐き出し というケー
In this post, we’ll discuss about the new File-Sharing and Document Support features in iPhone OS 3.2. The new File-Sharing feature allows user to access /Document directory through iTunes. Users are able to move files from their computers to iPads or iPads to their computers by using this feature. The new Document Support feature allows an application to register its supportive file types to the
Sphinx-Users.jp¶ Sphinx-Users.jp(略称#sphinxjp)は、美しいドキュメントを簡単に生成することができるドキュメンテーションツール、 Sphinx (スフィンクス)の普及を主眼としたコミュニティです。SphinxはPythonの公式ドキュメントだけでなく、このSphinx-Users.jpのサイトも含め多くのマニュアルやサイトで使用されており、詳細を Sphinxの歴史で紹介しています。 Sphinx-Users.jp は日本の Sphinx コミュニティです。 Sphinx-Users.jp では、日本で散らばっているSphinx関連情報を集めて、Webサイト、イベントを通じてSphinx情報を発信します。 slack のコミュニケーションや勉強会の開催などを通じて、ドキュメントをパワーアップしたい人、ドキュメントや翻訳で苦労している人、Sphinxの
Latest Published Version: http://www.w3.org/TR/html51/ Latest Version of HTML: http://www.w3.org/TR/html/ Latest Editor's Draft: http://www.w3.org/html/wg/drafts/html/master/ Previous Versions: http://www.w3.org/TR/2014/WD-html51-20140204/ Editors: WHATWG: Ian Hickson, Google, Inc. W3C: Robin Berjon, W3C Steve Faulkner, The Paciello Group Travis Leithead, Microsoft Erika Doyle Navara, Microsoft Ed
企画書には、市場規模・ユーザーニーズの裏付け等を説明するために調査データは入れたいところ。 ただ、資料作成で焦っている時ほど、検索しても良い情報が見つかりませんよね。そんな時は、今回ご紹介するサイトの中を覗いてみて下さい。スタートアップが投資家の方など社外向けに資料を作る時に、必ずや役に立つデータが見つかるはずです。 目次 【1】政府機関でデータを公開しているサイト(×2サイト) 【2】リサーチ会社の公開調査を横断的に探せるサイト(×3サイト) 【3】公開調査を見れる調査機関のサイト(×4サイト) 【4】自主調査の結果を公開しているリサーチ会社のサイト(+α) 【1】政府機関でデータを公開しているサイト 1.総務省統計局 総務省統計局のサイトでは、「国勢調査」「人口推計」から、「家計消費状況調査」「サービス産業動向調査」など様々な国内統計データが無料で閲覧できます。統計データ一覧はこち
クラフトワークの来日公演3-D CONCERTS 1 2 3 4 5 6 7 8を観にいったら、顔が大きいのか、3Dメガネがきつくて切なかったもりもとです。 株式会社ミクシィでは、新卒入社スタッフをはじめ、これからスマートフォンアプリ開発を行っていく全スタッフを対象に、社内で「スマートフォン開発研修」を始めています。その研修資料をこのたびgithubで公開させていただきました。 mixi-inc/iOSTraining · GitHub https://github.com/mixi-inc/iOSTraining mixi-inc/AndroidTraining · GitHub https://github.com/mixi-inc/AndroidTraining これら文書は、それぞれCC BY-SA 3.0およびApache License 2.0とCC 2.5 Attributi
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く