サイボウズのテクニカルライターはなにが違うの？ - Cybozu Inside Out | サイボウズエンジニアのブログ
このブログは、テクニカルライター/ローカライズ リレーブログの1本目の記事です。 こんにちは！サイボウズでテクニカルライターをしている小林（@kbys_psb）です。 最近、テクニカルライターが社内にいる会社が増えてきたのを感じています。 ただ、一口に「テクニカルライター」といっても、会社によって、仕事の内容や働いている環境は様々です。 今回は、サイボウズのテクニカルライターがどんな組織の中で仕事しているのか、どんな仕事の面白さがあるか、どんな人が活躍しているのか、などを紹介します。 「サイボウズのテクニカルライター」が所属している組織 テクニカルライターやローカライズを担当するメンバーは、これまで製品開発を支援する「テクニカルコミュニケーション」という独立したチームにいました（一部を除く）。 2024年の組織体制の変更に伴い、このチームがなくなり、各メンバーはそれぞれ製品ごとの開発チーム
情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
わかりやすい説明のための 10 の鉄則
第0部 まずは「分かりづらい説明」を知ろう（p.14～） 第1部 口頭説明編（p.25～） 第2部 資料作成編（p.63～） 第3部 スライド作成編（p.81～） スライドのまとめ（p.115～）
プレゼンスライドがみるみる良くなる基本の推敲技術 -事例付き解説-｜石原尚（大阪大学教員）
研究発表のスライドの仕上げの目的は、単に見栄えを良くすることではなく、伝えたいことが正しく・詳しく・分かりやすく伝わるようにすることです。スライドの推敲の技術を知って、実践的に身につけましょう。大阪大学大学院の教員であり、2021年10月に『卒論・修論研究の攻略本（森北出版）』を上梓した著者が実例付きで解説します。 スライドの推敲とは？文章がそうであるように、スライドもまた、「伝えたかったこと」をいつでも正しく伝えてくれるとは限りません。そして、正しく伝わるはずだ、という淡い期待を裏切られたときは、本当につらいものです。 文章を推敲するように、スライドにも推敲をかけましょう。ただし、スライドを推敲する際に、単にスライド中の語句を推敲するだけでは不十分です。スライドは、文章とは異なる表現形式だからです。 とはいえ、実は、著者の別記事で紹介した文章の推敲技術は、スライドの推敲にも使うことができ
プログラマーに贈る、わかりやすい文章を書くための技法 - LIVESENSE ENGINEER BLOG
これは Livesense Advent Calendar 2022 DAY 8 の記事です。 転職ドラフトでエンジニアをしている verdy_266 です。 僕の2022年を振り返ると、採用広報チームでの活動を無視することはできません。転職ドラフトの開発を行う傍ら、昨年末に採用広報チームにジョインし、記事の執筆や校正に多くの時間を割いてきました。 今まで記事を投稿したことがなかったこちらのブログにも共作含め5記事を投稿し、11月には Software Design への寄稿の機会をいただくこともできました。文章を書くことが思った以上に好きなんだなと発見があった年でもありました。 made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp 弊
【翻訳】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分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
ソフトウェアドキュメント作法 - maru source
こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました！ #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
git-notesでコミットにメモをつける - アジャイルSEの憂鬱
2020年に「コミットログは良くならない」というのを悟ったので、現実的な解決案である「git-notesでメモを残す」について記事を書いておきます。 前回の記事 sinsoku.hatenablog.com git-notes 詳細は git notes --help を読んでください。 概要は以下の通りです。 コミットログとは別にメモを残せる コミットはそのままなのでshaは変わらない shaが変わらないのでCIの再実行が起きない 他人のコミットにメモをつけられる 他人に作業を依頼する必要がない メモもリモートにプッシュできる 過去のコミットにメモを残せる 使い方 メモを書く git notes edit <sha> でメモを書くと、git log のときに一緒に表示される。 $ git notes edit d2cdf0b $ git log -1 d2cdf0b commit d2c
ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
ソーシャルゲームのクライアントエンジニア入門以前 というサイトを作って公開しました。 - izm_11's blog
ここで公開してます。 neon-izm.github.io 経緯 ソーシャルゲームクライアントは、Unity自体の知識に加えて、ソーシャルゲーム特有の慣習や挙動に合わせた知識が必要になります。 それらの個別実装についての記事は十分にありますし、サーバサイドも含めてソーシャルゲームを全部一人で作ってみる本もあります。 スタートアップ・個人で作れる スマホ向けUnity ソーシャルゲーム開発ガイド スタートアップ・個人で作れる スマホ向けUnity ソーシャルゲーム開発ガイド 作者:平野裕作発売日: 2020/01/17メディア: Kindle版 しかし、例えば独学でUnityだけを学んだ人や、スタンドアロンのゲーム畑からやってきた人がキャッチアップするための索引的な文書が見当たりませんでした。 （↑の本はある程度のサーバサイドとクライアントの事を理解している人が全体像を確認するための本で、サ
Build optimized websites quickly, focus on your content | Docusaurus
Build optimized websites quickly, focus on your content Powered by MDXSave time and focus on text documents. Simply write docs and blog posts with MDX, and Docusaurus builds them into static HTML files ready to be served. You can even embed React components in your Markdown thanks to MDX. Built Using ReactExtend and customize your project's layout by writing React components. Leverage the pluggabl
僕が考えた最強のAPIドキュメント生成 - 銀の人のメモ帳
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を使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
APIドキュメントブラウザDash用日本語版Docsetsまとめ
超速ドキュメントブラウザを日本語で 「Dash」は、多種多様なプログラミング言語やライブラリ、ツールのリファレンスを素早く引けるドキュメントブラウザ。 OS Xユーザでプログラミングをする人は、名前を聞いたことがあるはずです。 ドキュメントはDocsetsという形で150以上登録されており、ワンクリックでインストール可能。すぐに検索・参照できるようになります。本当に便利！ 便利というレベルを超越して、必需品のレベル。 OS X版とiOS版があります。 OS X版 Dash 3 – API Docs & Snippets. Integrates with Xcode, Alfred, TextWrangler and many more. カテゴリ: Developer Tools 販売元: Bogdan Popescu（サイズ: 11.8 MB） 全てのバージョンの評価: （19 件の評価
ESDoc - The Good Documentation For JavaScript - クックパッド開発者ブログ
こんにちは。会員事業部の丸山@h13i32maruです*1。 ソフトウェアのドキュメント(マニュアル)を書くには色々なツールや方法があります。 JavaScriptの場合はJSDocというドキュメンテーションツールがデファクトスタンダードです。 ですが、JavaScriptの最新仕様であるECMAScript2015(ES2015)がリリースされたことにより、 JSDocの競合として新しいツールが登場したり、JSDoc自体もバージョンアップしたりしています。 本記事ではそうした新しいツールの一つであるESDocを紹介します。 ESDocとは？ ESDocとは私が2015年4月から開発を行っている、JavaScript(ES2015)向けの良いドキュメントを作るためのドキュメンテーションツールです。 https://esdoc.org/ https://github.com/esdoc/es
API Design: A Documentation-first Approach - DZone
What exactly makes a “good” API? That is a question a lot of developers ask when designing their first API. While there are hundreds of resources online, all with differing opinions about what defines “good,” the majority of them share some similar themes. Logical endpoint naming conventions, clear error messaging, accessibility, and predictability are all crucial pieces in any well-designed API.
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Testing an API Against its Documentation
作業手順書に記載すべき項目のメモ - Qiita