【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック (1/3)：プロジェクト成功確率向上の近道とは？（2） - ＠IT
サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック：プロジェクト成功確率向上の近道とは？（2）（1/3 ページ） ITシステム開発の問題点の一つであるコミュニケーションの失敗。本連載では、これを防ぐ方法としてお勧めしたい3つのドキュメントを紹介していく。今回は、Joelの機能仕様書を日本人向けにカスタマイズされたものを例に、機能仕様書の基本的な書き方、読みやすくする7つのテクニック、仕様書作成ツールは何を使うべきか、誰が書くべきかなども解説します。 連載目次 連載の第1回の前回「ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門」では、ITシステム開発がビジネスに貢献していくためには、まずは開発の成功が出発点になること、そしてITシステム開発におけるコミュニケーションの重要性、そしてコミュニケーションにおけるドキュメントの重要性について説
Ruby の 定番対話ツール pry 徹底攻略 | Documentation browsing #pry #ruby - Qiita
Ruby の 定番対話ツール pry 徹底攻略 | Documentation browsing 概要 Ruby の 定番対話ツール pry 徹底攻略 ドキュメントの表示について 新しいライブラリやコードベースにおいて、メソッドのドキュメントを参照することはとても重要です。 Pry は外部ライブラリに依存することなく、ドキュメントを参照可能です。 Pry は必要なドキュメントを実行時にファイルから取得します。 Pry は gem install 時に 事前生成されたドキュメントに依存しません。 View method and class documentation show-doc show-doc でクラスやメソッドのドキュメントを参照します。 show-doc は RDoc と YARD の双方を理解し、シンタックスハイライトして表示します。 クラスのドキュメントを表示 [1] pry
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
背景 APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なREST APIドキュメントを作成する - Qiita これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。 markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
「東京メトロオープンデータ活用コンテスト」②APIの仕様設計を理解し、ドキュメント化する - Qiita
成果物：apiary.ioによる、APIドキュメント とりあえず見て貰えるとイメージつかみやすいです↑ あらすじ 100万円欲しいのでAPIを利用したアプリ開発を学ぶ絶好の機会なので、東京メトロオープンデータ活用コンテストに挑戦しようとしている。 前回、とりあえずざっと触ってみてAPIのイメージは掴んだ 今回は、公式ドキュメントと実際のレスポンスを咀嚼して、仕様設計を汎用ドキュメント化しつつ理解していくことを目的とする せっかくドキュメント化するからには、汎用性と実用性が高いフォーマットとしたい（オレオレにはしたくない） 成果物 API Blueprintで記述されたテキストをApiary.ioでホスティングし、以下を作った TokyoMetroOpendataAPI · Apiary github上のソース（markdownプレビュー版） やってみてわかった、ApiaryによるAPIドキ
APIドキュメントを実装と乖離させないために - Qiita
内部用APIであるか外部の開発者向けのAPIであるかに関わらず、ドキュメントと実装との乖離は極力避けたいものであるが、注意深く開発を進めない限りこの状況は容易に起こり得る。何が乖離を引き起こし、どうすればこの状況を回避できるのか考えながら、JSON Schemaの利用例を紹介する。なおこの投稿では、HTTP経由でデータの通信を行うような狭義のAPIのことをAPIと呼ぶことにする。 同じ情報源を参照する APIドキュメントと実装が同じ情報源を参照するようにすれば、論理的に関連した要素は統一的に変更され、これらの変更は完全に同期が取れたものになる。つまり、変更時に乖離が生じにくくなる。但し情報の見せ方によって乖離が発生する可能性は十分にだろうし、乖離が発生するのは理解しようとする側の認識の問題であるから、論理的に全く起こり得ないということではない。 この参照の形には、両者が別の情報源を参照する
AngularJSをはじめる前に#AngularJS入門その1 | DevelopersIO
AngularJSをはじめよう ここにあるように、最近はWebアプリを作成する際にJavaScriptのフレームワークを使用するのが当たり前といっていいくらい、 さまざまなフレームワークが存在します。 弊社ブログでもember.jsの記事等、JavaScriptのいろいろなライブラリ・フレームワークを紹介していますが、 私が近頃AngularJSを使用する機会があり、とても使いやすかったので、改めてここで紹介しようと思います。 AngularJSとは もう一度「AngularJSとはなにか」という部分を簡単におさらいを。 AngularJSはGoogleとコミュニティより開発しているオープンソース(MIT)のJavaScript用MVWフレームワークです。 テンプレート言語としてHTMLを使用できたり、双方向データバインディングやDI(依存注入)が使用できたりと、 近年複雑化するWebアプ
新人エンジニアに読んで欲しい英語ドキュメントまとめ (Ruby/Rails編) - Wantedly Engineer Blog
こんにちは！エンジニアの川崎です。 嬉しいことに、Wantedly開発チームの仲間は2013年の1年間で2倍に増えました。2013の最初には自分、 awakia と reikubonaga の3人でしたが、 デザイナなのにXCodeも使いこなす ferasyahin、 Chef使いのプロダクティビティ・エンジニア spesnova、それからこのブログのデザインもやってくれたエンジニア imaimiami の加入で合計6人になりました。最近ではさらに kento や shin-en がインターンとして活躍してくれています。 Wantedlyに入社してくるエンジニアは、なぜかRubyもRailsもやったことのない人ばかりなので(自分もそうでした)、 今日はそんな彼ら新人のために、Ruby/Railsで開発をするときに役立つページをまとめてみました。 初めてRails開発をする人に参考にして欲し
Ruby力を一段アップするために読んだほうが良い公式ドキュメント集 - Qiita
インスタンス化に関係する ::new, #new, #allocate と継承に関係する #superclass, #inhereted しか定義されていない。 その他のメソッドはすべてスーパークラスであるModuleに定義されている。Classはインスタンス化できるModuleと考えれば良い。 SuperClassの関係 [1] pry(main)> Class.superclass => Module [2] pry(main)> Module.superclass => Object [3] pry(main)> Object.superclass => BasicObject [4] pry(main)> BasicObject.superclass => nil [5] pry(main)> nil.superclass NoMethodError: undefined meth
英語表現でもう迷わない – ドキュメントコメント頻出表現まとめ | DOTAPON Blog
ドキュメントコメント、書いてますか？ githubで公開するライブラリなど、特に人に見せるようなコードには、きっちりコメントを入れておきたいものですね。 せっかくなら世界中の人に使ってもらいたいので、頑張って英語で書きたい。 でも、やっぱり英語には自信がなくて、何度も辞書や既存のドキュメントを見直してしまう…。 こんなムダな日々におさらばするため、代表的なドキュメントをいくつかピックアップして、頻出表現をまとめました。 もうこれで迷わない！ …いや迷うけど、それでも負担はグッと減るはず！ 参考ライブラリ Java – Java Platform SE 6 Closure Library – Closure Library API Documentation Foundation – Foundation Framework Reference UIKit – UIKit Framewor
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
エンジニアtype 技術者のキャリアを考えるWebマガジン - 転職＠type