【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
背景 APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なREST APIドキュメントを作成する - Qiita これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。 markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
Wordの代わりになる無料ソフト5選
こんなにも使えるものなのか！ ドキュメントの作成編集には欠かせない存在となっている、マイクロソフトのオフィススイート｢Microsoft Office Word｣ですけど、いかんせん、使いこなすには基本的に有料となるところが痛いポイントですよね。パソコン購入時に最初からバンドルされているというケースは問題ないのかもしれませんが、すべてがすべてそうではなく、最新の｢.docx｣フォーマットのドキュメントを扱うためにも、いざWordをお金を出して購入すべきかどうか？ そんな厳しい決断を迫られる場面に直面することは多々あったりするものです……。 もちろん、こうした事情はマイクロソフトも十分に心得ており、最近では｢OneDrive｣アカウントの保持者に対して、オンラインでWordを無料にて使えるようにするアプローチを取ってはいますけど、やはり製品版とは異なる機能制限などが悩ましいところです。なんと
Slate - Web APIのドキュメントを書く際にどうぞ！ MOONGIFT
Webサービスを提供していたり、スマートフォンアプリと連携するサーバを開発していたりすると必要になるのがWeb APIのドキュメントです。HTTPメソッド、パラメータ、返却値などが分かりやすく書かれている必要があります。 どういったドキュメントが読みやすいかは悩みどころですが、Slateは3ペインの構成になっていて見やすいのではないかと思います。ぜひご覧ください。 Slateの使い方 こちらがデモです。左が機能の一覧、中央が説明、右が実際のコードになります。 コードはShell、Ruby、Pythonで書かれています。 エラー時の内容も細かく書かれています。 Slateは一つのMarkdownファイルから生成されています。そのため単純なHTMLとして可読可能で、それをSlateを使って3ペインのより可読性高い形式にした訳です。Markdownで書く際に予めSlateの記法に沿って書いておく
CSSガイドラインを翻訳してみた - 技術日記＠kiwanami
Harry Roberts氏によるCSSガイドライン(High-level guidelines from writing manageable, maintainable CSS)のドキュメントが素晴らしすぎたので、勢いで翻訳してみました。（ロシア語、中国語、フランス語に引き続いて4番目...） 一般 CSS 注釈、アドバイス、ガイドライン at github 個人的な主観で見所を選んでみると、以下のような感じです。 クラスの名前付け方法（ネーミングルール） セレクターの設計、考え方 !importantの使い所 最近見るようになって来たBEM命名法についても説明してあります。 そもそもWebのデザインをどうするかという問題は置いておくと、CSSを書くという事は、どうやってそのデザインを実現するかというHowTo的なものと、どうのように名前付けやエレメントの設計を行なってメンテナンス可能
Dash - naoyaのはてなダイアリー
Twitter で知人に紹介したら周囲から「これは便利」という声が結構聞こえてきたので、ブログでも紹介しておこう。Dash というドキュメントビューワー。 iOS や RubyMotion、あるいは node や ruby そのほかのマニュアルをまとめてインクリメンタルサーチして API を調べる、ということができる。メジャーな色んな言語に対応している。 本来 Dash は "Snippet Manager" ということで、コードスニペットを管理するためのアプリケーションのようだけど自分は単なるドキュメントビューワーとしてしか使っていない。RubyMotion の勉強会に行ったときに、これが便利というのを教えてもらってその後愛用しています。主に iOS の開発のときに利用していた。 http://satococoa.github.com/blog/2013/01/22/view-rdoc-
英語表現でもう迷わない – ドキュメントコメント頻出表現まとめ | DOTAPON Blog
ドキュメントコメント、書いてますか？ githubで公開するライブラリなど、特に人に見せるようなコードには、きっちりコメントを入れておきたいものですね。 せっかくなら世界中の人に使ってもらいたいので、頑張って英語で書きたい。 でも、やっぱり英語には自信がなくて、何度も辞書や既存のドキュメントを見直してしまう…。 こんなムダな日々におさらばするため、代表的なドキュメントをいくつかピックアップして、頻出表現をまとめました。 もうこれで迷わない！ …いや迷うけど、それでも負担はグッと減るはず！ 参考ライブラリ Java – Java Platform SE 6 Closure Library – Closure Library API Documentation Foundation – Foundation Framework Reference UIKit – UIKit Framewor
新しい Java SE API リファレンスの入手先について
新しい Java SE API リファレンスの入手先について 2012年3月25日 at 10:30 午後 3件のコメント 2012 年 03 月 25 日、sun.com のドメインが利用不可になりました。これに併せ、java.sun.com で提供されていた Java SE API 日本語ドキュメントもオンライン経由で参照する事ができなくなりました。今後、日本語の Java SE API レファレンスはオンライン経由では参照できなくなりますので、アーカイブを御入手の上、ローカル環境でご参照ください。お手数をお掛けし申し訳ございませんが、どうぞ宜しくお願いします。 Java API の日本語ドキュメントはコチラから入手が可能です。 ドキュメントの再配布ポリシーはコチラをご参照ください。 新しい日本語 API ドキュメントのオンライン参照先URL (2012/4/11 訂正、追記) htt
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Apiary | Platform for API Design, Development & Documentation
AWS Documentation
ドキュメントKnockout.js
http://blog.inouetakuya.info/entry/2013/10/20/132928