GitLab的ドキュメント文化を組織にインストールする（実践編:スタートアップMNTSQの事例）｜Anno Takahiro
会社組織にドキュメント文化をインストールすることの有用性や、GitLabのような企業がどのようにドキュメントを運用しているかを、前回記事で書いた（スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ）。今回は、私のいるスタートアップのMNTSQ（モンテスキュー、と読みます）でどのようにそれを実践しているか、実際のところどのような成果が出ているのかについて書いてみたい。 MNTSQでは、当初からドキュメンテーションの重要性を経営メンバー全員で認識しており、社内ドキュメントをGitHub管理でメンテナンスしながら作り上げていくようにしていた。この大枠の仕組みの設計部分は弊社のデザイナーの生谷(@ikutani41)が初期に考案/メンテしたものである。デザイナー視点からこのような仕組みが設計され稼働されることは珍しいと思う。この辺については本人からもどう
私たちはどうして公式ドキュメントが読めないのか？ - Qiita
少しプログラミングを覚えてきた初学者が、さらに力をつけるために必要なのが公式ドキュメントを読むことだと思います。 公式ドキュメントには、日本語の記事には書かれていないような詳細な説明や、APIの使用方法、そしてリリースノートなど、実装には不可欠な情報が掲載されています。 しかし、公式ドキュメントが上手く読めずにつまづく人も多いのではないでしょうか？慣れていない人にとっては、技術について書かれたドキュメントを読むのは難しいものです。 この記事では、つまづいてしまう人が少しでも減るように、公式ドキュメントが読めない原因と対策をいくつか書いていきます。 公式ドキュメントとは この記事で言及している「公式ドキュメント」は、フレームワークやライブラリ、言語について、その公式組織が出している文書のことです。 具体的にはこのへん。 どうして公式ドキュメントが読めないのか 原因1. 公式ドキュメントを読む
Wordドキュメントの共有、編集・バージョン管理ツール | Hubble
契約書に関わるすべての人が、使いやすい。 これまでの煩雑な契約書のやりとり・管理はもう、おしまい。 スピーディーでミスのない契約業務フローを実現します。
エンジニアの文章、「上から目線」で書くから伝わらない
「ITエンジニアは文章を書くのが苦手だ」。こう言われることは少なくない。しかしシステムの機能仕様書や障害報告書など、ITエンジニアが書面で何かを説明する場面は多岐にわたる。そんなとき、ITの技術力がいくら高くても、相手に必要な情報を正しく伝えられなければ意味がない。 例えば、機能仕様書ならその機能はどういうものかを、専門知識が不十分な人でも分かるように説明しなければならない。また障害報告書なら、障害の内容や発生原因、対策の内容とその有効性について、関係者が納得するように説明する必要がある。相手を納得させる文章を書くことは、ITエンジニアの必須スキルである。 では、相手にうまく説明する文章を書くには、どのようにすればよいのか。端的にいうと、説明相手の立場や知識レベル、文章の作成目的に照らして「適切な情報」を選び、その情報を正確に、分かりやすく書いて、「適切に並べる」ようにすればよい。 ただし
ドキュメント作成時のあるあるアンチパターン20 - Qiita
業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)
「OWASPアプリケーションセキュリティ検証標準 v3.0」公開
JPCERT/CCは6月23日、OWASPの「Application Security Verification Standard（ASVS：アプリケーションセキュリティ検証標準）v3.0.1」日本語訳版を公開した。アプリケーション開発において満たすべきセキュリティ要件を19カテゴリに分類、まとめている。 日本語訳版が公開された「Application Security Verification Standard（ASVS：アプリケーションセキュリティ検証標準）v3.0.1」 OWASPのASVSプロジェクトは、アプリケーションの設計、開発、脆弱性診断などで必要とされるセキュリティ要件の標準を確立することを目指して活動している。公開されたASVSドキュメントは、2015年12月に英語版で公開されたv3．0をJPCERT/CCで日本語訳したもの。 掲載されているセキュリティ要件は、レベル1「
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
読みやすいREADMEを書く | Yakst
いくつかのオープンソースプロジェクトを公開している筆者からの、読みやすくユーザーにやさしいREADMEを書くためのアドバイス。 この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。 あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。 この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たの
脱ファイルサーバ！！個人でも会社でも使えるOSSのドキュメント管理システム！その名も「Alfresco」！
脱ファイルサーバ！！個人でも会社でも使えるOSSのドキュメント管理システム！その名も「Alfresco」！CMSインフラOSSAlfresco文書管理 はじめに ファイルサーバって重いし、ファイル探すの大変だし、ファイル名だけだとどれが目的のファイルかわからないし。。。 と感じた経験はありませんか？ 私も強く感じていて、いい感じのドキュメント管理システムないのかなと探していました。 DropBoxやOwnCloudも候補としてあったのですが、いまいち響かず。。 そんな中出会ったのが、「Alfresco」！ この出会いをみなさんに共有すべく、記事を書かせていただきました。 インストール作業は以下の記事を参考にしてください。 Alfrescoのインストール作業をコマンド単位で丁寧に記載します Alfrescoとは？ 参考:Alfresco公式ホームページ AlfrescoはCMS（コンテンツマ
CSSプリプロセッサでスタイルガイド - inkdesign
07 Dec 2012 ※この記事は、CSS Preprocessor Advent Calendar 2012の7日目の記事です。 CSS PreprocessorとIAの親和性、という記事の影響を受けまして、こちらの記事で書かれていた、 CSS Preprocessor そのものを共通ドキュメントにしてしまうとか という点を拾わせていただき、スタイルガイドのツールを紹介しようとおもう。 スタイルガイドとはなにか スタイルガイドは簡単にいうと、モバイル時代におけるCSSの設計と実装から引用させてもらうと、ページ上の部品（コンポーネント）をあつめたリスト、ページのこと。デザインパターンと呼ばれることもあるかもしれない。 具体的な成果物としてどういったものを指すのかというのは実際のページをみてもらう方が早いとおもうので、一度下記のページも参照してほしい。 MailChimp Design P
アンドロイドスマートフォンプライバシーガイドライン
「アンドロイドスマートフォンプライバシーガイドライン by タオソフトウェア」は、総務省のスマートフォンプライバシーイニシアティブに沿って、アンドロイドのアプリケーションプログラマが、 利用者が安心して利用できるアプリケーションを効率的に設計し、公開が行えるよう支援することを目的として、 アンドロイドのアプリケーションプライバシーガイドラインとしてまとめたものです。 総務省のスマートフォンプライバシーイニシアティブを原文として、アンドロイドのアプリケーションプログラマ（アプリケーション提供者）に必要な事項をピックアップし、 アンドロイド特有の要件を追加して再構成しました。 また、プライバシーポリシーの記載方法など、実際の運用に役立つように記載をしています 多くの方に利用して頂けたらと思いApatch License2として無償にて公開致しております。 一つでも多くのアプリケーションがプリバ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
「正しい」運用ドキュメントの書き方 /20160630-documentation-for-operation