情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
【翻訳】テスト駆動開発の定義 - t-wadaのブログ
このブログエントリでは、テスト駆動開発（TDD: Test-Driven Development）の考案者Kent BeckがTDDの定義を改めて明確化した文章を、許可を得たうえで翻訳し、訳者の考察を沿えています。 きっかけ 2023年の年末、テスト駆動開発（TDD: Test-Driven Development）の考案者Kent Beckは、substackにTDDに関するポストを連投して論戦を繰り広げていました。TDDはその誕生から20年以上が経ち、その間に「意味の希薄化」が発生して議論が噛み合わなくなっていました。意味の希薄化（Semantic Diffusion）とは、新しく作り出された用語が広まる際に本来の意味や定義が弱まって伝わる現象です。 私（和田）はTDDと関わりの深いキャリアを歩んできました。Kent Beckの著書『テスト駆動開発』の翻訳者であることもあり、TDDの正
【入門】要件定義
はじめに 最近プロジェクトマネジメント関連の仕事をする機会が増え、(駆け出しですが)要件定義や設計関連の業務もするようになったので、私の経験を基に要件定義の具体的なプロセスや考え方について、まとめていきます。 この記事の対象者 要件定義の基本や思考プロセスを学びたい人 エンジニアからプロジェクトマネジメントをやりたい人 ビジネスサイドとエンジニアサイドのコミニュケーション能力を向上させたい人 具体的な事例を通して要件定義を学びたい人 前提 紹介する内容はあくまで一例であり、プロジェクトやチームの状況に応じて調整が必要 あくまで自分(駆け出しPM)の経験に基づいた内容を言語化しています プロジェクト規模は10名〜20名のWebアプリ開発を想定しています システム開発の全体像 一般的なシステム開発のプロジェクトは下記のフェーズで進んでいきます。 ※ コンサルの領域だと要件定義の前に企画構想とい
ユーザのための要件定義ガイド 第2版 要件定義を成功に導く128の勘どころ | アーカイブ | IPA 独立行政法人 情報処理推進機構
デジタル技術を活用して企業のビジネスを変革し、自社の競争力を高めていく「デジタル・トランスフォーメーション（DX）」が注目を集めるなか、従来のようなITベンダやシステム部門が中心になって要件定義をすすめるスタイルから、業務部門のユーザが主体的に関与するスタイルへの変革の必要性が増しています。 システムの要件を定義する責任は、構築されたシステムを利用してビジネスに貢献する役目を負うユーザにあると言われています。しかしながら、システム開発の遅延の過半は要件定義の失敗にあると言われるように、要件定義においては、その過程で様々な問題に直面します。 そこでIPAでは、要件定義の過程で直面する問題への対応をガイドすることが、ユーザへのよりいっそうの支援策となると考え、「ユーザのための要件定義ガイド(初版)」の内容を一新し、「ユーザのための要件定義ガイド 第2版 要件定義を成功に導く128の勘どころ」と
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
ソフトウェアドキュメント作法 - 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日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
開発者が考える提案書テンプレート markdown版 - Qiita
概要 定型的な システム開発 では以下のような設計書が使われる。 システム要件定義 システム方式定義 ソフトウェア要件定義 ソフトウェア方式設計 ソフトウェア詳細設計 しかしそれ以前に 開発者目線、開発者発信で顧客に提案する概要資料を作りたい ケースがある。あるいは就職活動時の自身のポートフォリオを採用担当に説明することも同様かもしれません。 オードリー・タンがコード書く前にまずreadme.txtを書く話、Yahoo!がプロダクト開発の最初にプレスリリースから作る話、自分が前職で商品企画する際にまず広告から考えていた話、どれも明確なゴールイメージをまず確定させて必要要件を定義していくという意味で全部共通の考え方 — 菅俊一 / Syunichi SUGE (@ssuge) February 2, 2021 なんて話も。 技術とマーケティングのちょうど中間、開発者と顧客との意思疎通の橋渡し
LINEの社内には「テクニカルライティング」の専門チームがあります - LINE ENGINEERING
こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。今日は「テクニカルライター」というお仕事と、LINEにあるテクニカルライティングの専門チームについてお話しします。 テクニカルライターという職種があります テクニカルライターって何をしてるの？何を書くの？ ドキュメントはどうやって書いてるの？ どんなメンバーで仕事をしてるの？ ドキュメントを書く以外にこんなこともしているよ でもドキュメントを書くだけだと技術力が下がらない？ どんな人がテクニカルライターに向いてるの？ テクニカルライターという職種があります 私はもともとウェブ制作会社のインフラエンジニアでした。とある技術書を書いたことをきっかけに「テクニカルライターとして一緒に働きませんか？」と声をかけてもらい、LINEへ転職するに至ったのですが、実はお誘いをい
モダンな開発・運用環境を導入するために奮闘した(している)話 2nd - FJCT Tech blog
この記事は 富士通クラウドテクノロジーズ Advent Calendar 2017 の24日目の記事です。 昨日は @egoa56 さんの 「年末なんで大掃除(技術的負債のたな卸し)してみよう。」 という記事でした。 ステップ・バイ・ステップで、お掃除するために必要なチップスがまとまっていましたね。 はじめに 仕事では、 ニフクラ における企画・設計・開発・運営を担当している @ysaotome です。 富士通クラウドテクノロジーズ Advent Calendar 2017に参加するにあたり、 昨年、NIFTY Advent Calendar 2016 で掲載した ニフティ株式会社にモダンな開発・運用環境を導入するために奮闘した(している)話 が、その後どうなったのか？という事で、タイトル通り「モダンな開発・運用環境を導入し、定着させるために奮闘した(している)話 2nd」を書きたいと思い
コードを書く際の指針として見返すサイトまとめ - Qiita
お勧めの記事がありましたらコメントなどで教えて頂けると幸いです。 Guidelines プログラマが知るべき97のこと 技術的負債 不慣れなコードベースで短期間に生産性を高めるための7つの方法 何も知らない人を育てるために(新人教育情報キュレーション) 保守開発に開発者として入って困ることのまとめ(実体験) 技術系の名言まとめ++ 真似をする前にバッドプラクティスかどうかを調べてみよう 読まれない名著「人月の神話」を本気で読み込んでみた（まとめ） 技術的負債とどうやって戦うか 楽しいコーディングのための CUPID - SOLID 原則に対するアンチテーゼ エンジニア基礎(新人研修資料) Coding Style モデルやメソッドに名前を付けるときは英語の品詞に気をつけよう 関数名や変数名に使えそうな動詞・名詞・形容詞のメモ Naming -名前付け- DRY原則をもう一度 -コンカレント
ドキュメントの構造化による、良いドキュメントの作成方法 | gihyo.jp
あけましておめでとうございます。 ソフトウェアを開発し公開する場合、ドキュメント（マニュアル）を作成することが求められます。しかし、良いドキュメントを作成する方法というのはあまり知られていません。どのようにすれば良いドキュメントを作成できるのでしょうか？ 本稿では、ソフトウェアと同じくドキュメントを要素と性質に構造化することで、良いドキュメントを作成する方法を紹介します。そして、その要素と性質に対してアプローチを行っているESDocというJavaScript（ECMAScript2015）向けのドキュメンテーションツールについても簡単に紹介します。 対象とするドキュメント ドキュメントと一口にいっても仕様書、設計書、マニュアルなど様々な種類が存在します。そこで、本稿が対象とするドキュメントを「ライブラリやフレームワークなどを開発するソフトウェア開発者自身が、そのソフトウェアの使い方をエンド
開発のドキュメントをどこに置くか問題 - $shibayu36->blog;
最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは
プログラミングスタイルガイドのスタイルガイド - Qiita
本文書は、プログラミング言語向けのスタイルガイドに向けたスタイルガイドである。 本文書へのフィードバックはQiita上のコメントにて受け付ける。 構造 対象を明確にする そのスタイルガイドがどのような状況のどのような対象に向けたスタイルガイドであるか規定すること。 状況や対象は広すぎてはならない。 理由: 対象はスタイルガイド記述者には自明かもしれないが、似て非なる言語に誤用されたり、特定分野のアプリケーション向けスタイルガイドが他分野のアプリケーションを理不尽に拘束したりすることがある。これを防ぐべきである。 良い例: 「本文書はRuby on Railsアプリケーション向けのスタイルガイドである」 「本スタイルガイドはX社におけるRubyプロジェクトに適用すべきスタイルを規定する」 悪い例: (何も書かない) 「本文書はX社におけるすべての開発に適用される ... 述語メソッドや述語関
プログラマが欲しい仕様書とは
3. ソフトウェア工学とは • ソフトウェアの開発・運用・保守に ついて体系化、分析、研究する分野 • 高度で安全なソフトウェアを短期間 で設計するための研究を行う
頑健なJavaプログラムの書き方
日頃より、アレスネットをご愛顧いただきまして誠にありがとうございます。 「ホームページサービス」のサービス提供は2016年1月31日をもちまして終了させていただきました。 これまで長らくご利用いただき、誠にありがとうございました。 今後も、皆様によりよいサービスをご提供させていただけるよう、サービス品質向上に努めて参りますので、何卒、ご理解いただけますようお願 い申し上げます。 ＜アレスネットをご契約のお客様へ＞ 後継サービスとして「userwebサービス」を提供させていただいております。 詳しくは、以下のリンクをご参照ください。 ▼「userwebサービス」のご案内 http://www.ejworks.info/userhp/alles/index.html 今後ともアレスネットをご愛顧いただけますようお願い申し上げます。 株式会社イージェーワークス アレスネット カスタマーサポート
ウノウラボ Unoh Labs: ブラウザから使用できる仕様書を書くツールまとめ
GT Nitro: Car Game Drag Raceは、典型的なカーゲームではありません。これはスピード、パワー、スキル全開のカーレースゲームです。ブレーキは忘れて、これはドラッグレース、ベイビー！古典的なクラシックから未来的なビーストまで、最もクールで速い車とカーレースできます。スティックシフトをマスターし、ニトロを賢く使って競争を打ち破る必要があります。このカーレースゲームはそのリアルな物理学と素晴らしいグラフィックスであなたの心を爆発させます。これまでプレイしたことのないようなものです。 GT Nitroは、リフレックスとタイミングを試すカーレースゲームです。正しい瞬間にギアをシフトし、ガスを思い切り踏む必要があります。また、大物たちと競いつつ、車のチューニングとアップグレードも行わなければなりません。世界中で最高のドライバーと車とカーレースに挑むことになり、ドラッグレースの王冠
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方 目次 この文書について 設計文書のうまい書き方 なぜ設計文書を書くのか 良い設計とは何か 同僚の開発者に向けて書く 第 1 節に書くこと: プロジェクト/サブシステムの目的を示す 第 2 節に書くこと: 設計に使う高レベルなエンティティを定義する 第 3 節に書くこと: 個々のエンティティに関する低レベルの設計を書く 使い方 設定 モデル 相互作用 第 4 節に書くこと: 利点, 前提, リスク/懸念事項 マネージャ向けに書くこと 最後に 設計文書のうまい書き方 この文書について "How to Write an Effective Design Document" の日本語訳です. http://blog.slickedit.com/?p=43 推敲歓迎: 誤訳, タイポ, 訳語の不統一,
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
TestDox - TestDox