大手ITスタイルガイドがベースGoogleやMicrosoftなど大手IT企業の英語スタイルガイドの基準がベース。一般的な英語表記から外れません。
いくつかのオープンソースプロジェクトを公開している筆者からの、読みやすくユーザーにやさしいREADMEを書くためのアドバイス。 この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。 あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。 この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たの
devdocs.io 最近，GitHub Trending Repositories のページで devdocs.io という便利なサービスを知りました． devdocs.io は複数のドキュメントを素早く横断的に検索できるサービスです．多分使ってみると一瞬で分かるので詳細は省きますが，各言語や DOM，React などのフレームワークのドキュメントをサクッと検索できます．どのドキュメントを有効/無効にするかも選択でき，IndexDB を使ってローカルにドキュメントを置くことでローカルでも利用できます．いつでも devdocs.io を開くだけで使えますし，モバイル対応もしています． また，Ruby 2.2 と Node.js が入っていればローカルでも簡単に立てられます．デフォルトでもウェブデベロッパーにとってうれしいドキュメントがたくさん入っていますが，さらに Scraper を使って
Ruby Weekly is a weekly newsletter covering the latest Ruby and Rails news. DocBox is the latest attempt to improve the Ruby/Rails documentation scene. Created as a Google Summer of Code project by Ian Ownbey (mentored by Jeremy McAnally) DocBox "sits on top of RDoc and allows users to update documentation through a wiki-like interface." Changes to the 'wiki' are then folded back into your code an
はじめてのバグジラ このドキュメントはBugzilla-jpを利用するのに必要な知識やノウハウを提供しています。もし、このドキュメントの内容が不十分だったり、間違った記述を発見した場合、Bugzilla-jpにプロダクト:mozilla.gr.jp、コンポーネント:bugzilla-jpでバグとして報告してください。 このドキュメントの読み方 このドキュメントは目的に応じて読み分けることができるように、複数の章に分割されています。Bugzilla-jpを利用する全ての利用者は第一章と第二章は必ず目を通す必要があります。 そして、それ以外にもあなたのとりたい行動(たとえばバグを報告したい等)にあわせて、その手順を紹介したドキュメントを読む必要があります。 このドキュメントは各手順の単なる説明書ではなく、その際に決まっている様々なルールを明文化しています。このルールに従わない方の参加は多くの開
職場でここ３〜４ヶ月の間、システム再構成のためのドキュメント化プロジェクトというのを進めてきた。その中で『ドキュメントを書く』ということに対する意識が随分自分の中で変化したので、メモしておく。 まずは経緯から。 そのシステムは、いわゆるレガシーなシステムで、十数年来の歴史を持つ。これまで基盤が多少変わることがあっても基本的にソフトウェアアーキテクチャ（どのような単位で機能をモジュール化するか、どのように機能を抽象化し変化に対して柔軟にするか）に変わりはなく、作った当初の設計にツギハギしてメンテナンスを続けていた。 元々は、一体何をすれば増員以外の手段で開発量を上げられるかということを議論していた。現行のアーキテクチャのままでは求められる開発期間とバージョンアップのサイクルに対して近い将来限界を迎えることが明白であったためだ。 今のアーキテクチャや設計に問題があり、メンテナンス性を大いに損ね
もっとも「ロジック」というのも程度問題なのだけど、 少なくともプログラム言語で記述するレベルでのロジックを書くというものではありません。 いや、特定の企業ではそういう書類を（しかもプログラム前に！）書かせるように強要してきたりするけども。 参考：IEEE830-1998におけるソフトウェア仕様書（内部）の書き方 そもそも業界ではさも当然のように「外部仕様書」とか「内部仕様書」という言葉を使っていたりしますが、 あまりきっちりした定義はありません。上記でも「内部仕様書」という定義ではないわけですし。 各社の文化で独自に解釈されているのが実情ですかね。 ニュアンスとして外部/内部というのはI/O境界面からの外部/内部といった感じ。 他のチーム(別会社だったりする)とかとやり取りするために、この機能は外から見たらこんな感じ、というのが外部仕様で、 中はこう言う風に作るっていうのが内部仕様とされま
ソフトウェア開発において断定しにくい問題としてドキュメントをどうするかということがあります。ドキュメントに関してはおおよそソフトウェア開発を仕事としている人すべてが何らかの形で考えざるを得ない問題です。 日経ソフトウェアに「俊敏な開発のためのプログラミング 悪徳の栄え」というYugui(園田裕貴)さんが書かれているコラムがあります。普段、断定しにくいことに関して一旦断定することによって問題をはっきり見えるようにしようという趣旨のコラムだと個人的には解釈しています。第５回のコラムには以下のように書かれていました。 プログラムの仕様書はテスト・コードとして書くべきです。そうすればより精密に記述できますし、いつでも自動化されたテストによって検証可能になるからです。仕様書を自然言語で書いたとしても、それは「自動実行できないテスト・コード」かそれ以下のものでしかありません。逆にテスト・コードは、その
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方 目次 この文書について 設計文書のうまい書き方 なぜ設計文書を書くのか 良い設計とは何か 同僚の開発者に向けて書く 第 1 節に書くこと: プロジェクト/サブシステムの目的を示す 第 2 節に書くこと: 設計に使う高レベルなエンティティを定義する 第 3 節に書くこと: 個々のエンティティに関する低レベルの設計を書く 使い方 設定 モデル 相互作用 第 4 節に書くこと: 利点, 前提, リスク/懸念事項 マネージャ向けに書くこと 最後に 設計文書のうまい書き方 この文書について "How to Write an Effective Design Document" の日本語訳です. http://blog.slickedit.com/?p=43 推敲歓迎: 誤訳, タイポ, 訳語の不統一,
悪態のプログラマとある職業プログラマの悪態を綴る。 入門書が書かないプログラミングのための知識、会社の研修が教えないシステム開発業界の裏話は、新人プログラマや、これからプログラマを目指す人たちへのメッセージでもある。 自称職業プログラマの私だが、最近はプログラミングをしている時間はどんどん少なくなってきた。遂には顧客向けにシステム導入の提案書を書いている始末である。 技術者が提案書を作ると、システムの機能面を強調しがちだ。特に、事前に客先の担当者と打合せをし、システムの要件がある程度決まっているような場合には、いわゆる「能書き」の部分は「当り前のこと」として省略してしまう。「能書き」とは「そもそもそのシステムを導入することによるメリットは何であるか」といった、根本的なところの説明である。 確かに、顧客の担当者が読むだけなら「能書き」は必要ないだろう。しかし、彼がその提案書を上司に読ませたら
昔の同僚が退社してベンチャー仕事をやるという. 門出を祝う宴会に, 昔のよしみで呼んでもらった. ついでに古巣の近況を聞く. ひとつ嬉しい知らせがあった. 以下その自慢話. ある夏, 私は社内ライブラリのチュートリアルを書いた. そのチュートリアルが, 今でも改訂されながら参照されているという. のみならず新人プログラマの研修教材として広くとりいれられつつあるそうだ. 私はとても嬉しくなった. もちろん手柄は改訂を続け, 様々な改善を続けた彼らのものだ. それでもなお私は喜びを隠せない. 自分が去った今も文章だけが生き続けている. 私は平凡なプログラマだから, 自分のコードが生き残れるとは思えない. 一方ボランティアで仕事の合間に書いた文章は読み継がれている. 価値のあるものが生き残るのなら, 私のなした価値は(コードではなく)文書にあったことにある. プログラマとしては悲しいけれど, 会
The Taglets Collection is a utility suite around the JavaDoc tool. It offers: Preconfigured Tags A suite of preconfigured extended tags for like formatting the text of JavaDoc comments. Examples include: @adm $Revision: 1.11 $ $Date: 2008/03/30 12:43:22 $ for automated inclusion of formatted repository keywords or {@table ...} for simple tabular. Built-in Generator Tags Support for well-known gene
前回「言葉の不統一がもたらす業務とシステムへの悪影響」では、システム開発プロジェクトは用語を統一する良い機会であり、用語辞書を作成することを提案しました。しかし、用語辞書の作成には大変なエネルギーが必要で、事前に用語辞書のポイントをしっかりと押さえておかないと大変なことになります。 またプロジェクトメンバーがその苦労に勝る便利さを期待、実感できるようなものでないと、用語辞書を完成できずに終わってしまう可能性もあります。用語辞書の完成には、用語辞書に便利な機能を付加することも大きなポイントとなります。 用語辞書の項目 用語辞書として必要な項目は、以下のとおりです。 業務で使用する用語 システムで表示スペースに制約がある場合に使用する略語 用語の意味 用語を使う職場 同じ意味の用語。システムに使用しない用語 記載・更新・削除した作業者名とその日付 調査当時、その用語や同義語を使用している帳票名
に尽きます。はい。ということで、スペジェネで実は一番便利かもしれない、でも多分ドキュメントには書いてない色んなマスタ管理方法(*1)です。 (*1) ここで言う「マスタ管理」は「コード」→「名前」のリゾルブ処理のことです
Ringo's Weblog さんで紹介されていた Tim Berners Lee の提案書が面白い。一読されることをオススメします。素晴らしい文書をご紹介・翻訳して下さっている ringo さんに感謝。 1990年にTim Berners Leeが提出した、最初のWebブラウザ開発の提案文書は、優れたプロジェクト・マネジメントの手本となる文書である。 と書かれているとおり、何かが目を見張るほど卓越した提案書というわけではないが、非常にバランスが取れ、よく練られた内容の提案書になっている。（特殊な技法が使われていてスペシャルな存在になっているとかいう類ではなくて、ベーシックなスキルの積み重ねで全体として高品質な提案書になっている。） 個人的に好きな点は、 見通し：やりたいこと、やりたくないこと やらないこと の項。 この言い回しは、技術文書だとわりと見かけるのだけど、他の界隈ではあまり見な
« JavaScript の String 型を継承する | メイン | JavaScript は、なぜプロトタイプベースなのか » 2006年10月18日 JavaScript を学ぶ上で読むべきウェブサイト JavaScript について議論する際、良く挙げられる参照文献は ECMA-262 (日本語版) です。 しかし、どちらかというと ECMA-262 は JavaScript の処理系を実装する人に向けた文書なので、JavaScript を使いたい人には向きません。 私は、 JavaScript のユーザーには、mozilla developer center の Core JavaScript 1.5 Guide (日本語版)Core JavaScript 1.5 Reference (日本語版は整備中?)が良いのではないか、と思っています。 Mozilla のドキュメントかよ
上司にITを使わせる秘訣は1ページのマニュアル!?：目指せ！シスアドの達人－番外編（4）（1/2 ページ） 前回、坂口が作ったマニュアルをテストしていた谷田だが、すぐに行き詰まってしまう。そこに現れた松嶋の指摘によって、坂口のマニュアルには「複数の操作を1文で説明しており、分かりにくくなっている」という欠点があることが分かった。その後、谷田の協力もあり、坂口はその欠点に気付き、ついにマニュアルを完成させるが……。 いよいよ坂口が作ったマニュアルの真価が問われるときが 坂口と谷田が協力して作ったマニュアルが完成してから、1週間後の新営業支援システムプロジェクト定例会。議題を一通り終えたところで、坂口が口を開いた。 坂口 「皆さん、お願いがあるんです。今後の討議をスムーズに進めたり、情報共有したりする手段として、やはり電子会議室を使いたいんです。いまからマニュアルを配りますので、これだけ覚えて
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
