ドキュメントが欠かせない理由欧米の企業とお仕事するときにいつも感心するのがドキュメントのボリュームと質。私も結構書く方だと思っていますが、それを容易に上回る情報量のドキュメントが共有されることがあります。ただ単に文字数が多いわけではなく、必要十分な情報が図なども交えて明文化されています。 エンジニアに限らず、デザイナーやプロダクトマネージャーもしっかりドキュメントを書く習慣が根付いているように見えます。恐らく下記の理由からしっかりドキュメントを書かざるを得ないのかもしれません。 皆が同じ時間帯で仕事をしているわけではない場所も違うので「ちょっと話してすり合わせ」とはいかない英語が第一言語ではない人たちとコミュニケーションをしている文化も違うのでお互いがもつ『当たり前』が通じない日本企業で日本語で通じ合える環境では馴染みがない状況です。ドキュメントを書かなくても、ちょっと話せば分かり合える場
こんにちは。ruremaメンバーの id:Pocke です。 Rubyの日本語リファレンスマニュアルで、未翻訳の英語のドキュメントが公開されるようになりました。 この記事では、それについて簡単に解説します。 何が変わるのか 今までは、未訳のメソッドは日本語リファレンスマニュアルには一切書かれていませんでした。 それが今回の変更によって、英語のリファレンスマニュアルと同じ文章が、そのまま日本語リファレンスマニュアルにも書かれるようになります。 たとえば Ruby 2.7で追加されたModule#const_source_locationメソッドのドキュメントは未訳であるため、今までは日本語リファレンスマニュアルにはドキュメントが存在しませんでした。 ところが今回からは次のようなドキュメントが日本語リファレンスマニュアルにも存在するようになります。 https://docs.ruby-lang
最近 hitode909 さんが、ここ最近ドキュメントについて書いているのを読んで、 Creating Documentation in an Agile Scrum Environment チームのScrapbox3000ページくらいを見返して整理した The Product is Docs: Writing technical documentation in a product development group そういえば、Increment が Documentation 特集だった号 があったなあと思い出したので、読んでみた。 Increment は Stripe のやっている雑誌 (という話は2017年にも書いた)。もともとはオンライン雑誌だったのだけど、今は紙版も売っている。といっても Airbnb Magazine や Offscreen のように、実際に本屋で売っていた
いまやプレゼンの必須ツールとなっている「パワーポイント」だが、アマゾンでは禁止されているらしい。アマゾンの「普通」は、他の会社の「普通」とは異なることが多々ある。ではアマゾンの「普通の基準」とは何なのだろうか。アマゾンジャパン元経営メンバーが解き明かす。【「amazonの絶対思考」（扶桑社）から一部抜粋】 ◆◆◆ アマゾンでの社内プレゼンテーションで、パワーポイントの使用が禁止されているのは、かなり有名な話になってきた。「パワポ禁止令」を発令したのは、他ならぬジェフ・ベゾスだ。 ベゾスがパワポを禁止した理由については、社内でもさまざまな逸話が語り継がれている。なかでも、私がさもありなんと思っているのが、外部コンサルティング会社にまつわるエピソードだ。 アマゾンがスタートした当初、サービスの骨格を固めるためにベゾスは外部のコンサル会社に提案を依頼した。彼らは当然気合いを入れたパワポの資料を作
目次 はじめに 読者に対する心がけ 誰がその文章を読むのかを考えよう 読者は何を知っているかを考えよう 読者がどんな感じを受けるかを考えよう 読者と対話する気持ちになろう 自分に対する心がけ 書こうとせず、読もうとしよう 読もうとせず、読みはじめようとしよう 何でも書いていいんだよ 惜しげなく人に与えよう 人からのものには敬意を払おう 魔法の呪文は毎回発見しよう まず自分がよく理解しよう 知識を誇るために書くのをやめよう その他の心がけ 言葉についての心がけ 長い文は注意して使おう 書いたものは必ず読み直そう 適切な例を示そう 言い換えの練習をしよう ８割でよしとしよう すべてを動員しよう その他の心がけ 環境についての心がけ 人の「気」を意識しよう 頑丈で軽い文章作成のツールを使おう その他の心がけ 編集者に対する心がけ 助言はよく聞こう 自分の状況を正しく伝えよう 感謝の気持ちを忘れな
「シャープが多くなるほど文字が大きくなる」というイメージ（利点）にはわかる部分もあるのだけど、自分が構造的な文章（つまり見出しをわざわざ付けるような文章）を書くときって、後から「もっと大きい見出しがほしい」なんて思うことはほとんどなくて、「さっきまで付けていた見出しより小さい見出しがほしい」と思うことのほうが多い。
Powered by GatsbyStarting from v2, Docz is entirely built using GatsbyJS. It's optimised for a lightning fast development experience and speedy build times. This also allows you to leverage GatsbyJS's huge ecosystem of plugins and tools. Zero configNo need to worry about complex configuration settings to build and run your documentation. With Docz you can create customizable sites with a single co
普段仕事をしてるとき、いろいろなことに気を使いながら仕事をしてると思う。たとえばissueには、その背景、やりたいことや期待する効果、制限事項、認識している副作用やリスクの情報等などを書くような運用ルールを作っているチームは多いらしい。しかし、私たちのチームではそういうルールはない。それでうまくいくんだっけっていう話をよく質問されるので、考えてみた。 コードの品質をカバーするためのコメント私たちは、常にわかりやすいコードを書けるとは限らない。解説として、コメントが役立つ場面はある。 ちょっと待ってよ「よし、Why notを書こう！」と言って上手く書けるのは、そうとうに経験を積んだ人だ。そして、経験を積んだ人は大体問題ない。悪いコードほどコメントが必要だが、良いコメントが書けるくらいならコードはもっと良くなってる。鶏と卵じゃん。 コメントについて議論する暇があったら、コードについて議論したほ
こんにちは、mzpです。最近は、毎日だれかが体調不良で休んでいて、恐怖に震えています。 最近、esaのカテゴリを整理しており、とうとう「その他」というカテゴリを廃止できました。 今日はその話を紹介します。 背景 Misocaでは情報共有ツールとしてesa.ioを利用しています。 ただ、当初からQiita:teamを使っており、2015年の中盤にesaに移行しました。 このとき、Qiita:teamにあったすべての記事は自前のスクリプトで移行しました。 その際、esaのカテゴリに相当するものがQiita:teamにはなかったため、とりあえず「その他」カテゴリ以下にすべての記事を分類しました。そのため以下の画像のように、その他カテゴリ以下には1000本以上の記事が分類されていました。 問題点 この状態のまま1年半ほど過してきたが、以下のような問題が生じてきました。 目的の記事に辿りつくのに常に
業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)
The tiniest owl, the Elf Owl, is only 5 inches tall. A group of owls is called a parliament. Owls can turn their heads as much as 270 degrees. They’re owlways watching you.
Messengerプラットフォームの概要では、プラットフォームの仕組みとプラットフォームの実装を成功させるために何が必要であるかを詳しく説明しています。 Messenger from Metaは、ビジネスやソーシャルメディアに興味を示した人に対して、ビジネスのFacebookページまたはInstagramプロアカウントで返信できるようにするメッセージサービスです。利用者とビジネスのアカウント間の会話は、利用者側が開始する必要があります。 Messengerプラットフォームは無料でご利用いただけます。 処理の概要利用者は、FacebookまたはInstagramにログインしている間に、ビジネスページまたはInstagramプロアカウントにメッセージを送信します。またはモバイルアプリやウェブサイトにアクセスしている間に、Metaプラグインで送信します。ビジネスページまたはInstagramプロ
To start building a bot using the Messaging API, you must first create a channel on the LINE Developers console. What's a channel? To use the LINE platform, your application must be linked to a channel. When a channel is created, a unique channel ID is issued to identify the channel. Channels must have a name, description, and icon image. Creating a channel Step 1: Log in to the console Log in to
RedPen is a proofreading tool to help writers or programmers who write technical documents or manuals that need to adhere to a writing standard. RedPen automates the verifications of input documents written in natural languages — NOT computer languages such as C++ or Java. RedPen はプログラマや記者が規約にしたがって文書（マニュアルやソフトウェアドキュメント）を記述しているか検査します。 RedPen は自然言語で記述された入力文書のチェックを自動化します。 Customizable 柔軟な設定 RedPen is
There are endless ways to use the world’s simplest API (it only has one endpoint…). If you run a blog, a website, a shopify online store or any other kind of service, you’ll be able to boost your engagement with the Yo API. Some example use cases: A blog can Yo the readers whenever a new post is published. Imagine getting a Yo From PRODUCTHUNT.An online store can Yo its customers whenever a new pr
Twitter で知人に紹介したら周囲から「これは便利」という声が結構聞こえてきたので、ブログでも紹介しておこう。Dash というドキュメントビューワー。 iOS や RubyMotion、あるいは node や ruby そのほかのマニュアルをまとめてインクリメンタルサーチして API を調べる、ということができる。メジャーな色んな言語に対応している。 本来 Dash は "Snippet Manager" ということで、コードスニペットを管理するためのアプリケーションのようだけど自分は単なるドキュメントビューワーとしてしか使っていない。RubyMotion の勉強会に行ったときに、これが便利というのを教えてもらってその後愛用しています。主に iOS の開発のときに利用していた。 http://satococoa.github.com/blog/2013/01/22/view-rdoc-
Ruby 2.0以前向けのリファレンスや、過去のリリースを入手したい場合には、SourceForge.jpのプロジェクトページからお願いいたします。 Rubyリファレンスマニュアル chm版リミックスは、SourceForge.jpの提供するホスティング・サービスを用いて配布されています。 使い方・注意事項 Windows OSをお使いの方 ダウンロードしたzipファイルを展開して、中に含まれているchmファイルをそのまま開いていただければ、閲覧することができます。 Windows以外のOS（Mac OS X, Linuxなど）をお使いの方 chmを閲覧できるソフトウェアを導入の上、ダウンロードしたzipファイルを展開して、中に含まれているchmファイルを開いてください。 動作確認はとれていませんが、Mac OS XであればiChmやCHM Viewなどが使用できるようです。 公式リファレ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
