conventional-changelog実践チームトポロジー： プラットフォーム性とイネイブリング性の戦略 / Practical Team Topologies in Timee
データベースドキュメント管理システム dmemo のご案内 - クックパッド開発者ブログ
こんにちは、みんなのウェディングに出向中の小室 (id:hogelog) です。 今回はクックパッドとみんなのウェディングで利用しているデータベースドキュメント管理システム dmemo を紹介します。 https://github.com/hogelog/dmemo dmemo を作成し導入した経緯 私は2016年3月頃からみんなのウェディングで Redshift, bricolage, embulk, re:dash 等を利用したデータ分析基盤の構築を進めています。 (みんなのウェディングのデータ分析基盤の現状 - みんなのウェディングエンジニアリングブログ) 社内の誰でも扱えるデータベース、データの集約・計算・加工、ダッシュボードの作成、クエリの共有などは上記ブログ記事でも書いたように Redshift, bricolage, embulk, re:dash 等を組み合わせることで実現
わかりやすさの技術 - やしお
社内向けの教育資料を、ど素人でもわかるようにと思いながら作っていて、じゃあ「わかりやすい」って何だろうって考えてた。今まで読んできたいろんなわかりやすかった本とそうでない本を思い浮かべながら、一般的にここを注意すればわかりやすさを確保できるだろうっていうポイントを一旦まとめておこうと思った。そうしてまとめてみると、本に限らず人に何かを伝えること一般に適用される話だなと思った。 読む側の負担を減らす わからない＝理解をはばむ障害物がある。この障害物を取り除く／回避する作業が「わかる」ために必要になる。その作業を、作者ではなく読者が負担するとき「わかりにくい」本になる。 日本社会だと情報の受け手の側がこの「わかる」ための作業を負うことでコミュニケーションを成立させる傾向にある。空気を読むというようなことだ。そのため発信者側が事前に手を尽くしてわかりやすく発信するというのが苦手で、相手が汲み取っ
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
ドキュメントの継続的な開発方法 | IIJ Engineers Blog
私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント
Read the Docs(Sphinx)でオープンソースのドキュメントをいい感じに書いてみる
B! 139 0 0 0 最近良くGitHubなんかで公開されてるオープンソースのドキュメントを見ようとすると こんな感じの似たようなフォーマットで書かれているものが多くなっています。 余りに多いので最初GitHubのサービスかな、とか思ったんですが、 これはまた別のRead the Docsという ドキュメント用ホスティングサービスによるものでした。 Read the Docs Read the Docsでドキュメントを公開してみる Sphinxのインストール レポジトリ側の準備 Read the Docsへの登録 ページを作成 Indexページ ページ内容の編集(Markdown to reStructuredText) タイトル ハイパーリンク 画像 リンク付き画像 インラインマークアップ コードブロック リスト テーブル Pythonのモジュール説明 その他reStructured
社内Wikiに情報を書くときに守ってほしい、たったひとつのルール - 無印吉澤
このページについて これは、社内 Wiki に情報を書くときに、私が個人的に守っていて、チームメンバにもできるだけ守ってほしいルールの紹介記事です。このルールを実際に運用するためのコツについても、基本ルールの派生という形で紹介します。 想定する環境 この記事は、社内に Wiki があって、フォーマットが決まったドキュメント（仕様書や手順書など）とは別に、各人がメモを自由に書いて共有できるような環境を想定しています。 Wiki の種類は問いません。PukiWiki、MediaWiki、Confluence、Esa、Redmine などのプロジェクト管理ツール付属の Wiki などなど……何でもいいです。Word 文書などにも適用できなくはないですが、文書を気軽に分けるのが難しい場面には、あまり向かないかと思います。 ルール：「このページについて」という欄をページの先頭に用意し、そのページの概
ドキュメントで利用可能なIPアドレスなど
が用意されているそうです。 AS番号 [RFC5398] Autonomous System (AS) Number Reservation for Documentation Use で定義されています。 64496 から 64511 16ビット AS(2バイト AS) 65536 から 65551 32ビットAS(4バイトAS) 一見すると、プライベートASっぽく見えますね。 MACアドレス MACアドレスそのものは IEEE で定義されていますが、ドキュメント用のアドレスに関しては [RFC7042] IANA Considerations and IETF Protocol and Documentation Usage for IEEE 802 Parameters で触れられています。00-00-5E は、IEEEからIANAにアサインされたOUIです。このレンジから、様々な用
ドキュメント作成システム構築ガイドを読んだ - プログラマでありたい
気になっていた『ドキュメント作成システム構築ガイド』が、Kindle版になっていたので読みました。最近の私の関心テーマおよび課題とマッチしていたので、なかなか興味深かったです。 本書の内容 本書の概要は、Amazonさんには下記のように公開されています。 アプリケーションの開発手順，製品のユーザマニュアルなど，ドキュメントの多くはエンジニアによって作成されています。ドキュメントの品質が低い場合，読み手が誰であっても内容の理解に時間がかかります。ドキュメントは簡潔で内容を正確に伝えるものでなければなりません。エンジニアにとってドキュメント作成は避けて通れません。いまやドキュメント作成はコーディングと同様にエンジニアに必要な技術なのです。本書は，ソフトウェア開発の技法に基づいてドキュメント作成を支援するシステムを構築します。このシステムではGitを用いたバージョン管理，GitHubによる共同編
Full featured documentation deployment platform
Documentation simplified Build, host, and share documentation, all with a single platform. Sign up now Easy previews and deploys Preview changes on every commit to your pull requests. Release documentation to your users on each merge. Ideal developer experience Write documentation without changing your workflow or your tools using a docs as code approach. Work privately or publicly Easily share wi
ドキュメント作業で楽をしたい - NaCl Blog
プログラマがあまりやりたがらない作業のひとつとしてドキュメント作成がよく挙げられるかと思います。 〇〇仕様書とか〇〇設計書とか〇〇手順書などの作成作業ですね。 特に成果物がdocxやxlsxのようなプレーンテキストでない場合、次のような理由で気が滅入る方も多いのではないでしょうか。 手慣れた道具(エディタ)を使うことができない 専用のソフトでよくわからない機能が裏で勝手に動いたりしてて気持ち悪い 変更履歴をトラッキングしづらい、差分をマージしづらい Markdownでさくっと書いてそれっぽいものができれば、GitHubのWikiなどにぼちぼち書き溜めておいて最後にコンパイルするみたいなやり方ができるなぁとか、そうすればわざわざドキュメント専用リポジトリを作ったりする必要もないなぁとかモヤモヤしながらいろいろ調査・検討したので以下の4構成でまとめたいと思います。 Pandocについて Pan
esa.ioと HackMDでつくるいい感じの議事録&ドキュメント管理 | ShareWis Blog（シェアウィズ ブログ）
こんにちは。ShareWisの辻川です。 みなさん社内のドキュメント管理には何を使っていますか？ チャットツールは各社優れたサービスを出していますが、なんとなくSlackがデファクト・スタンダードになりつつあるのかな、と思う今日このごろですが、ドキュメント管理に至っては、まだまだデファクトと呼べるものは出てきていないように感じます。 弊社でも、今まで、Basecamp、WordPress、asana、Sign、Googleドキュメント… と色々なサービスを使ってきました。 色々経た結果、今はesa.io + HackMDという2つのサービスを組み合わせて使うかたちに落ち着いています（といっても最近になって落ち着いたので、すぐに変わるかもしれませんが）。 今回はそんな社内の議事録 & ドキュメント管理ツールについてご紹介します。 なぜデファクトなドキュメント管理サービスが出てこないのか社内で
swaggerでAPIドキュメントを書いたらめっちゃはかどった話 - kaz29
Swaggerは、REST APIの仕様とそれに関連するツール群の総称です。REST APIの仕様を定義したJSONファイル(Swagger Spec)を軸に以下のようなツールから構成されています。 Swagger UI - Swagger Spec から動的にAPIドキュメントを生成するツール Swagger Editor - Swagger Specのエディタ Swagger Codegen - Swagger Specからクライアントのコードを生成するツール 最近では、Open API InitiativeがAPIの記述のためにSwaggerを採用して話題になりました。 www.publickey1.jp APIドキュメントのメンテは結構面倒 一般的にAPIの仕様書は、古くはExcel/Wordなどを使ったり、最近ではWikiやMarkdown形式で記述したりなどプロジェクトによって
僕が考えた最強の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を使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
free-programming-books/free-programming-books-ja.md at master · EbookFoundation/free-programming-books · GitHub
Index 0 - 言語非依存 アクセシビリティ オープンソースエコシステム ガベージコレクション グラフィックスプログラミング グラフィックユーザーインターフェイス セキュリティ その他の話題 ソフトウェアアーキテクチャ ソフトウェア品質 ソフトウェア開発方法論 データベース ネットワーキング 並列プログラミング 機械学習 正規表現 理論計算機科学 組み込みシステム Android AppleScript AWK Bash C C++ Clojure CoffeeScript Common Lisp Coq D Elixir Emacs Lisp Erlang Git Go Groovy Gradle Grails Spock Framework Haskell iOS Java JavaScript Angular.js Backbone.js jQuery Node.js React
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 件の評価
Springfox+Swagger+Bootprintによる即席REST API仕様書作成 - Taste of Tech Topics
こんにちは。阪本です。 世の中、Swaggerが注目を浴びてきていますね。 開発のスピードアップが求められる中、「外部IF仕様書なんて書いてられねぇ！！」なんて言って実装をバリバリ進めてしまいそうですが（アカンアカン）、そうは言っても外部IF、他社との仕様調整も必要。 そんなときに有効な、実装しながら仕様書も作れるSpringfox+Swaggerに加え、ドキュメント生成ツールのBootprintを使って、簡易的な仕様書を作ってみました。 仕様書の動的生成 以下のようなシンプルなSpringBootアプリケーションから、REST APIを生成してみます。 @SpringBootApplication public class SwaggerExampleMain { public static void main(String[] args) { SpringApplication.run
ドキュメントシステムはこれを使え2015年版
Sphinx Con JP 2015での発表 目的からドキュメントシステムを選べるYes/Noチャートは33ページにあります。 （当初アップロードしたものはこのページにミスがあったので差し替えています。高橋さんありがとうございます。）Read less
REST APIドキュメント生成パターン - ✘╹◡╹✘
REST API用のドキュメントを生成するときにどうやってるかについて雑記を残しとく。 概要 実装とドキュメントの乖離を避けるためには、同じ意味情報を二箇所以上に定義することを避ける必要がある。そのための方法として、実装それ自身か、もしくは実装が参照している何らかのメタデータを元にしてドキュメントを生成したり、テストの実行結果からドキュメントを生成するというパターンがある。 テストから Cookpadでは、autodocというライブラリを利用して、RSpecでテストを実行している途中で得られたメタデータからドキュメントを生成している。これはテストの実行結果からドキュメントを生成するパターン。 これは実現方法としてはかなり特殊な部類。このパターンが最も効果的に働くのは、ドキュメント生成のために余分な開発コストはあまり掛けたくないが、テストは真面目に書いている OR 真面目に書いてほしい、とい
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - TechBooster/AndroidOpenTextbook: オープンソースで作るAndroidの教科書です
