ESM アジャイル事業部 開発者ブログ

永和システムマネジメント アジャイル事業部の開発者ブログです。

ふりかえりには Continuous KPTA がオススメ

こんにちは、コッパイ星を救うため惑星探索している nsgc です。

組織活動やチームでの開発をよりよくするための「ふりかえり」。
アジャイルなソフトウェア開発を実践しているチームでは、プラクティスとして取り入れて実施している所も多いかと思います。

私が参加しているプロジェクトでは2週間イテレーションで開発しており、リリースした日の夕方に「KPTA」(けぷた)を使ってふりかえりを行っております。

KPTA とは、こちらをご覧いただくと詳しく載っていますが、ざっくりと説明しますと「続けること(Keep)」、「問題点(Problem)」、「試したいこと(Try)」の3つの項目に分けて整理する思考フレームワークである「KPT」を拡張したもので、Try から具体的な行動することを Action として抽出することに注力できるのが特徴になります。

当初、私達はホワイトボードに模造紙を貼り、その前でペンと付箋紙を用いて行なっていたのですが、昨年、同僚の @amapyon@kunitoo が開発している Web上で KPTA でのふりかえりが出来るサービス 「Continuous KPTA 」 がリリースされたので、プロジェクトでのふりかえりをそこで行なうようになりました。

それから1年ほど使ってみた上で、ぜひ皆さんにオススメしたいと思い、今回ブログに書かせてもらいました。

付箋の関連付けが簡単にできる

Continuous KPTA の素晴しい点として、画面いっぱいに広がったKPTAボード上の好きな所に付箋の配置ができ、付箋同士に線を引くことで簡単に関連を結べることです。
これにより、「ある Problem を解消するために、この Try を考えた」ということを分かりやすく表すことが出来ます。

relation
Problem から Try、Try から Action と繋がっている

もちろん、ホワイトボードや模造紙でも線は引けますが、1度線を書くと付箋の位置が動かしずらくなったり、毎回ホワイトボードの線を消したり模造紙を貼り変えるのが手間である、という理由から中々線を引きずらいと思ったことはありませんか?
そのため簡単に関連の線で引けることはとても魅力的なことと私は思います。

ふりかえり自体を見直せる

Continuous というその名前が表すように、実施したふりかえりを次に繋げていくというコンセプトがあり、過去に実施したふりかえり結果がすぐに閲覧できたり、出した意見が長く残り続けているということが可視化されています。

そのため、「最近は Problem が増加傾向になっている」とか 「長く放置されている Action がある」といった、ふりかえり自体の状態の把握が容易にできます。
このことは「解決できない Problem が多い」、「実践しにくい Action になっている」など付箋に書き出した内容を考察するきっかけになり、ふりかえりによる改善活動自体の見直しにも繋がります。

problem
付箋の上に過去の世代が。黄色の付箋は5回前から Problem として残り続けている

便利な機能がそろっている

ふりかえりの基本的なやり方が載っていたり、タイムキーパーをするためのタイマー機能、そして、どの意見にフォーカスして議論するかを参加者が選ぶ投票機能、と実際に行う時にあると便利な機能が揃っているのも嬉しい点です。

vote
赤の数字バッジが投票結果。たくさん出た Try からどれを試すかを決めるのにも使える

最後に

昨今はコロナ渦による外出自粛のため、リモートでチーム開発をしているという開発者の方も多くいらっしゃるんじゃないでしょうか。
もし、一箇所に集まれないためふりかえりがあまり出来ていない、良い方法やツールがなくて困っているというチームがありましたら、1度試してみてはいかがでしょうか?

Continuous KPTA

AWS ECS + Active Storage(AWS S3) で秘匿情報を秘匿して利用する方法

안녕하세요.이토 쿠니히코입니다.*1
Nizi Project から韓国ドラマやK-POP を聞くようになった kunitoo です。

Webアプリケーションを書いていると、アイコン画像やPDFなどファイルをアップロードして保存したいというケースに遭遇すると思います。私が関わってきたプロジェクトではファイル添付する要件が十中八九入っていました。
ファイル添付を実現する Ruby のライブラリは様々ありますが、Rails 5.2 から標準でファイルをアップロードして Active Record モデルにファイルを添付する機能の Active Storage が利用できるようになっています。

今回は RailsAWS ECS で動作させる場合に Active Storage + S3 を Rails サーバーを介して利用する際に秘匿情報を秘匿して利用する設定方法について書いていきます。

簡単な設定方法

Rails ガイド Active Storage の概要 2 セットアップAmazon S3サービスを利用する設定方法について以下のように記載されています。

# config/storage.yml
amazon:
  service: S3
  access_key_id: ""
  secret_access_key: ""
  region: ""
  bucket: ""

一番簡単な設定方法としては、IAM で S3 にフルアクセスできるユーザーを作成し、アクセスキーを発行して、その access_key_id, secret_access_keyYAML に記載するという方法があります。

しかし、この方法はセキュリティとしてあまりよろしくありません。 よろしくない点としては以下があります。

  1. IAM ユーザーのAWS S3 アクセスできる権限が強すぎるため、Active Storage に利用するバケット以外にもアクセスできてしまう
  2. IAM のアクセスキーは流用することができるため、今回利用したい Rails サーバー(ECS) 以外からもアクセスすることができ、キーが漏れると悪用される可能性がある

秘匿情報を秘匿した設定方法

今回はアクセスキーを作成せずに、ECS に必要な必要最低限の権限を付加することで、安全に Active Storage を利用する方法を紹介します。 設定のポイントは以下です。

  • S3 Bucket を private で作成する
  • S3 Bucket にアクセス可能な必要最低限の IAM ポリシーを作成する
  • ECS Task ロールに IAM ポリシーをアタッチする

以下に Terraform を使って実行可能な具体的な設定を記載します。

S3 Bucket を private で作成する

Active Storage で利用する S3 を private で作成します。 これにより、外部からのアクセスを防ぎます。 この状態ではどこからもアクセスができません。

resource "aws_s3_bucket" "images" {
  bucket = "${local.server_subdomain}images.example.com"
  acl    = "private"
}

S3 Bucket にアクセス可能な必要最低限の IAM ポリシーを作成する

ここのポイントは Rails ガイドにも記載されている、s3:ListBucket、s3:PutObject、s3:GetObject、s3:DeleteObject の4つのパーミッションを付与することと、resources に bucket/ とbucket を指定する点です。
はじめはすべてのオブジェクト (bucket/
) の指定だけで動作するかと思ったのですが、 バケット全体 (bucket) の指定がないと Active Storage で purge をする際に失敗します。

data "aws_iam_policy_document" "allow_s3_policy" {
  statement {
    actions = ["s3:ListBucket", "s3:PutObject", "s3:GetObject", "s3:DeleteObject"]
    resources = [
      "${aws_s3_bucket.images.arn}/*",
      "${aws_s3_bucket.images.arn}"
    ]
  }
}

resource "aws_iam_policy" "allow_s3_policy" {
  name        = "${var.environment}_allow_s3"
  description = "allow s3 bucket"

  policy = "${data.aws_iam_policy_document.allow_s3_policy.json}"
}

ECS Task ロールに IAM ポリシーをアタッチする

ここのポイントはタスク実行ロールではなくタスクロールにIAMポリシーを設定する点です。
参考のため、ECS task definition を定義する部分までを載せていますが、aws_iam_role_policy_attachment が重要な点です。

resource "aws_iam_role_policy_attachment" "ecs_task_role_allow_s3" {
  role       = aws_iam_role.ecs_task_role.name
  policy_arn = aws_iam_policy.allow_s3_policy.arn
}

resource "aws_iam_role" "ecs_task_role" {
  name = "${var.environment}EcsTaskRole"
  path = "/"

  assume_role_policy = "${data.aws_iam_policy_document.ecs_assume_role_policy.json}"
}

data "aws_iam_policy_document" "ecs_assume_role_policy" {
  statement {
    principals {
      type        = "Service"
      identifiers = ["ecs-tasks.amazonaws.com"]
    }
    actions = ["sts:AssumeRole"]
  }
}

resource "aws_ecs_task_definition" "server" {
  family                = "${var.environment}-server"
  container_definitions = data.template_file.server_container_definitions.rendered
  execution_role_arn    = aws_iam_role.ecs_task_execution.arn
  task_role_arn         = aws_iam_role.ecs_task_role.arn

  network_mode = "awsvpc"

  cpu                      = 256
  memory                   = 512
  requires_compatibilities = ["FARGATE"]
}

Active Storage の設定

ポリシーを設定することで Rails の設定から access_key_id, secret_access_key は不要になり以下を書いておくだけでよくなります。

# config/storage.yml
amazon:
  service: S3
  region: ap-northeast-1
  bucket: <%= ENV.fetch("AWS_S3_BUCKET_NAME") %>

まとめ

AWS ECS で Rails サーバーを動かす際の Active Storage の設定を IAM ポリシーを適切に設定することで、アクセスキー管理せず、より安全に S3 を利用できるようになりました。
また、具体的な設定方法として Terraform で示しました。
(いくつか記載していないリソースがあるのでそのままでは動作しませんが、実際に構築し動作させたものをベースに記載しています)

AWS で Active Storage を使う際の参考になればと思います。

*1:こんにちは。伊藤邦彦です。

私が思う読みやすいコード

どうも。今は保守をメインの業務にしている muryoimpl です。

今回は、私がこうなっていると読みやすくて嬉しいなぁというコードについて、頑張って言語化していきたいと思います。

明確な指針を出しにくいものなので、リーダブルコードやリファクタリング Ruby エディションには載っていないかもしれないですが、今から書いていくことが意識されているコードを私は読みやすいと思うので、こういう観点もあるのね、くらいの気持ちでお付き合いください。

メソッドを見れば流れがわかる、短期記憶にやさしいコード

私は局所を見るよりも、まず全体の流れがわかったうえで詳細を読むほうが理解が進むタイプの人です。 メソッドの全体の流れがわかると、流れからどの部分で何が行われるかだいたい想像することができるので、詳細を見に行ったときに予めイメージを持っておけるし、イメージがわけば考える範囲を限定できるため、100%手探りよりも効率がよいと感じるからです。

流れがわかると、「考える範囲を限定できる」というのが重要です。そのメソッドのもつ役割と振る舞いにだけ集中してそのメソッドを読めばよいからです。読み進めていくうちに記憶しておくべきことを少なくできると、頭の中がクリアな状態を保てるため、理解も進みます。

ただし、読むべきメソッドが限定できたとしても、そのメソッドが極端に長かったり、複数ファイルにまたがって深いところまで追っていかないと最終的な結果が何をしているかわからなくなっていたりする場合、脳の短期記憶がオーバーフローしてしまい、よくわからなくなってしまいます。こういう場合、戻ることも難しくなって読みなおし、ってなることがあるんですよね。

例えば、他のファイルにあるメソッドへの参照がない10行のメソッドと5,000行のメソッドでは読み進める中で記憶しておくことは 5,000行のメソッドのほうがきっと多くなります。同じ 10行のメソッドでも、同一ファイル内で完結しているメソッドと複数のファイルにまたがって定義されているメソッドをあれこれ組み合わせた10行のメソッドでは後者のほうが記憶しておくことは多いでしょう。

短期記憶を酷使しない脳が疲れないコードが読みやすいやさしいコードだと思うのです。

流れがわかるコード

原則として、コードは上から下に順に処理されるようになっています。上から下に読み進めていくというのは、時系列に処理を追うことができるので読みやすい、というのは同意いただけるのではないかと思います。まず、上から下に読んでいけるようなコードの構成にしましょう。

メソッドや変数が流れを理解できる程度にわかる名前がついていると、更に読みやすくなります。変数やメソッド名は処理の目次に等しいと私は思っているので、これは大事です。概要が名前からわかると、その部分については読む/読まないの判断をつけやすいため無駄に調べる必要がなくなり、読む人にとっては非常やさしくなります。名前についてはリーダブルコードの「第Ⅰ部 表面上の改善」でいろいろと触れられているのでそちらを参照してください。

以下のコードは bin/rails g scaffold User した controller の create メソッドのコードを一部加工、抽出したものです。user_params メソッドを読むのにちょっと下のほうにジャンプして戻ってこなければいけませんが、基本的にファイルの上から下に読み進めていけます。

class UsersController < ApplicationControllerdef create
    @user = User.new(user_params)

    respond_to do |format|
      if @user.save
        format.html { redirect_to @user, notice: 'User was successfully created.' }
        format.json { render :show, status: :created, location: @user }
      else
        format.html { render :new }
        format.json { render json: @user.errors, status: :unprocessable_entity }
      end
    end
  end

  private
    def user_params
      params.fetch(:user, {:first_name, :last_name})
    end
end

私は複数のオブジェクトが相互作用するようなメソッドを作成するときは、いつも controller のメソッドを思い浮かべます。このように流れがわかるようになっているか?それぞれの変数、メソッドは目次的な役割を果たしているか?と自問しながら実装しています。

主となるオブジェクトに対する操作がわかるように書かれている

定義しようとしているメソッドの中で、主となるオブジェクトに対する操作が見えるように記述レベルを揃えて書くことを意識すると、処理の流れが見えるコードになります。

先ほどの UsersController#create の例では、User モデルのインスタンスが主とするオブジェクトと設定されています。このメソッドの中で扱おうとしている User モデルのインスタンスに対する操作の様子が見えるように処理が書かれているため、流れがわかりやすくなっています。

「記述レベルを合わせる」とは、オブジェクトの生成から操作終了までを一貫してここのメソッド内に書くということです。open や close のような対になっている処理については、必ず同じメソッド内に記述します。open はあるのにclose がないと、本来セットで現れるべきものが現れないため不安を煽りますし、close を探す必要が出てきてしまいます。

場合によっては別のオブジェクト(例: Service クラスや Form Object など) に渡して処理をお願いすることもあるでしょうが、その場合は主とするオブジェクトに対して何をしているのかが明確にわかる名前にする必要があります。先に書いたように、変数やメソッドは目次に相当するので名前は重要です。必ず、主とするオブジェクトに対する操作がわかるような名前をつけましょう。

これらを3分クッキングに例えるならば、料理をする際はまな板のある作業台(今定義しようとしているメソッド) の上で材料を扱い、手順をみせます。手順のうち時間のかかるものについては「こちらに予め準備しておいたものがあります」とアシスタント(Serviceクラスや Form Object) に依頼して作ったとしても、必ずできあがったそれを作業台の上で扱うことで全体の流れと操作がわかりやすくなるようになっています。これと同じイメージです。 大きな処理を作る場合は、アシスタントの処理もアシスタント側で作業台の上で操作するようにすると、更にわかりやすくなると思います。

まとめ

今回は、私の読みやすいと思うコードということで、全体の流れがわかるコード、短期記憶を酷使しないコードが私にとっては読みやすいコードです、ということを表明し、どうすればそうなるのかについて少しだけ触れてみました。

構成だけでなく読みやすさ/読みにくさを考えてコードを書くのは大変な行為なのですが、ファイルやコードの構成上優れていたとしても読みにくいコードは理解しにくいものです。理解がしにくいと手を入れるモチベーションが低下してしまうので、大変ですが将来修正する自分のためだと思ってやっていきましょう。

アジャイル事業部の営業担当の話

平田です。

アジャイル事業部で営業を兼ねたマネージャをやるようになってから6年が経ちました。 それ以降チーム開発をする普通のプロジェクトにメンバーとして参画することがなくなり、非常に寂しい限りです。マネジメントや事務的な仕事が多くなったのですが、意外と楽しめている自分に気がつきました。 その中でも一番楽しめているのは、お客様からの相談を受ける営業の仕事です。

マネージャになる以前もプログラマをメインでやるというよりは、要求アナリスト的な振る舞いをすることが多かったため、その時の仕事の入り口だけを繰り返してやるような仕事をすることができているのです。 「こんな課題感があるからこういう風にしたい」「こう進みたいと思うのでこのような人を追加したい」など、様々な相談をいただけるのですが、要求アナリスト的に動いていた時の習性もあり、「それが本当にやりたい/やるべきことですか?」ということを少し失礼なくらいしつこく聞いてしまいます。

プログラマを追加して早く開発したい」「アジャイル開発が流行っているから(上司に言われたから)はじめたい」というような要望をお持ちのお客様にとってはちょっと面倒な反応をしてしまっているなと自分でも感じてしまうのですが、その後に仕事を任せるプログラマに最高の仕事をしてもらうためにも、「真の要求」に少しずつでも近づいて仕事を開始できるようにしたいと考えています。

でもアジャイル事業部で言う「プログラマ」はプログラミングのみを行うのでなく、開発チームのディレクション以下、開発に関係するすべてのことを担当するので、1時間の打ち合わせで方向付けを終わらせたつもりの僕の成果に関係なく、現場でお客様と話をした結果の方向に変えていることが多いです。これは個人的に少し複雑な気持ちになります。

本来であればチームメンバーとして一緒にやるのがベストですが、違う役割を担当する中でも、お客様のビジネスやサービスが良い方向に向かうために、その時にできる中で最善の行動に取り組んでいくというのはとても安心感があります。

と、ここで宣伝です。 そんな仲間と一緒に仕事をしてみたいと少しでも思った方、ぜひ一度お話させてください!

agile.esm.co.jp

プログラミング多言語主義

ちかごろプライベートではElixirばかり書いているe.mattsanです。

かつてはC/C++で仕事をしていました。 Object Pascalを使ったこともありますし、わずかですがLuaプラグインを書いたこともありました。 アセンブリ言語と格闘したこともあります。

みなさんは、何種類ぐらいのプログラミング言語を使っていますか?


わたしたちは、業務ではRuby on Railsを中心に開発を行っています。 Railsで開発をしていると、少なくともRuby, JavaScript, SQL の三つの言語を扱うことになります。

DSLをひとつの言語として含めると、Railsのルーティングも専用の言語で記述しているので、日頃から多数の言語を使いこなしていることになります。

今回は複数の言語を使うことの意味について考えてみたいと思います。


プラットフォームや環境の制限で、特定の言語を使用しなければならないことは多々あります。 そういった制約がなかったとしたら、複数の言語を使用する必要はあるのでしょうか。

例えばRubyを「プログラミングの母語」とする人にとって、データベースの問い合わせにもRubyを使えたら。 Active Recordは一つの解答です。 Active Recordのおかげでデータベース上のデータをRubyのオブジェクトとして扱えるようになりました。 それでも背後にあるデータベースを意識しないと、非効率な操作をしてしまったり、余計なオブジェクトを作ってしまったりすることがあります。

データベースのデータを扱うには、オブジェクトを扱う視点だけでなく、データの集まりを扱う視点がどうしても必要になってきます。 そんなときSQLを使うときの視点が役に立ってくれるはずです。

そんな視点をもたらしてくれることが、たとえ普段はほとんど書くことがなくても、SQLを使えることの意味の一つなのだと思います。


複数の視点を持つことの意味について考えるとき、「金槌の法則」を思い出します。 プログラミングに限らず、わたしがいつも気に留めるように心掛けている法則の一つです。

「金槌の法則」

クリスマスプレゼントに金槌をもらった子どもは、何でも叩きたがる。

ただ一つの道具しかもたない専門家は、ねじ釘を叩きかねない。

G.M.ワインバーグコンサルタントの秘密」

使い慣れた道具ばかりを使っていると、問題に合った解法を選択する代わりに、解法に問題を当てはめようとしてしまいかねません。

プログラミング言語は、それぞれ得意とする領域を持っています。 ある分野の問題を解決するために開発されたものであったり、解法を言語仕様に反映したものであったりします。 たとえばオブジェクト指向プログラミングを実践するためのオブジェクト指向言語があります。

ときおり引き合いに出されるように、オプジェクト指向プログラミングはオブジェクト指向言語でなくても可能です。 よほど特殊な事例と思われるかもしれませんが、プラットフォームや環境に制限がある中では、そのような状況が発生します。

個人的な経験では、電子機器の組み込みソフトウェアの開発がそのケースでした。 設計はオブジェクト指向でなされていますが、その環境で使用できる言語はC言語に限られるというケースです。 ありがたいことにその開発では、オブジェクト指向設計を念頭に開発されたライブラリを利用したため、そのライブラリにそった使い方をしていればオブジェクト指向を促されるようになっていました。

しかし、オブジェクト指向プログラミングそのものを知らなければ「何か勝手が違う」と文句を言いながら、ライブラリを使うだけになっていたかもしれません。 開発そのものではオブジェクト指向言語を使う機会がなくても、オブジェクト指向言語を使えるということが役に立ってくれたケースです。

では、新しい言語を使おうと思い立ち、READMEやドキュメントのtutorialを消化したら、次はどこに進むとよいでしょう。


わたしは、同じ問題を様々な言語で解いてみることをお勧めします。

そのとき、一つの言語でいくつもの書き方を試してみます。 他の言語の書き方を再現できないか。 他の言語ではまねできないような書き方ができないか。 今まで使うことのなかった関数や演算子を使うとどうなるか。 いろいろな方法で書いてみると、それぞれの言語の特徴を知ることができます。

あえて何度でも車輪を再発明する。

ときには、こんな解法があったのか、という驚きに出会えます。 今までにない解法を見つけたら、今度は普段使っている言語でその解法を使うとどうなるか探ってみます。

それを繰り返していくことで、言語によって得意な領域があること、今まで気付かなかった問題の捉え方があることを体験できるでしょう。 それが複数のプログラミング言語を学ぶ意義の一つだと考えています。


複数のプログラミング言語を学ぶとき、たとえそれぞれは自由に使いこなせるようにはなれなくても、思考の道具として役立てることができると信じています。

…と、ここまで、御託を並べましたが。 様々な問題を様々な方法で解けるようになることは、単純に楽しい行為です。 使えるプログラミング言語を増やして、そのような楽しみも増やしてください。


Rails / OSS パッチ会オンライン 2020年11月のお知らせ

2020年11月の Rails / OSS パッチ会を 11月5日(木)にオンライン開催します。

この会をひとことでいうと、日頃のお仕事で使っている Rails をはじめとする OSS への upstream にパッチを送る会です。

会には RubyRails のコミッターである顧問の a_matsuda もいますので、例えば Rails に送るパッチのネタがあるけれど、パッチを送るに適しているかの判断やパッチを送る流れが悩ましいときなど a_matsuda に相談して足がかりにするなどできます。

開催時間は 17:00-19:00 となりますがご都合のあう方はぜひご参加下さい。Google Meet あたりのテレビ会議システムを使います。

当日の招待 URL は Idobata の esminc/rails ルームで共有する予定です。

idobata.io

特に募集ページなど設けませんが、上記理由から Idobata のアカウントと (TV 会議システムによっては Google アカウント) が必要になると思います。

以下、前回の活動が関わる成果です。

koic: The Ruby Style Guide (and RuboCop)

github.com

github.com

yucao24hours: Adhoq

github.com

その他の開催方針については以下の Gist に記していますので、ご参照ください。

gist.github.com

[復刻]ドキュメント記述の心構え

2004年中途入社の koic です。来月で入社17年。長いですね。 17年の間で人や技術が流転する長い勤務の中で伝承の途切れを観測していることから、私がいまの勤務先に入ったころ Wiki への考え方への影響を受けたものを発掘してみました。今回、私的解釈を交えて一般公開します。

はじめに

本記事で取りあげるのは 2006年以前に「ドキュメント記述の心構え」 (WikiName は DeciplinesOfWritingDocumentsOnWiki) として作成された Wiki ページを掘り起こしたものです。かつて角谷さんが牽引していたプロジェクトにて引き継がれていた文書で原文ママで置いています。Wiki 記法は数多ある Wiki クローンの Ruby 製の Hiki による記法です。

『ドキュメント記述の心構え』原文

{{toc}}

! 木構造よりも、ネットワーク構造を好め
* Wikiページはツリーノードというよりは、ネットワークノードだと思え。
* 孤立したノード間を繋げるものがハイパーリンクである。
* ただし、視点ごとに整理した木構造のインデックスページの作成は、奨励される。

! ネストしたリストよりも、見出しによる構造化を好め
*リストは使い易いが、それゆえに濫用しがち。それは本当にリストか?
* リストはインデントが深い
* 見出しを使えばTOCプラグインでページの目次を自動生成できる

! リストで文章を区切るよりも、空行をあけてPタグでレンダリングせよ
* それは本当にリストか? 簡潔な地の文の連続を、適切なまとまりで段落とせよ

! 安易に項目追加する前に、リオーガナイズを検討せよ
* 特定カテゴリの一覧となるインデックスページを適切なサイズで分割せよ

! 正規化と重複の均衡点を探せ
* DRYと読み下しやすさとのバランスに唯一無二の解決策はない。コンテキスト毎での最適なバランスを探せ

! PREとQUOTEを使い分けよ
* 難しいよね

! リオーガナイズのメカニクスを用意せよ
* TODO: まとめてみること :-)

私的解釈

掘り起こした文書への私的解釈です。

{{toc}}

見出しによる目次 (Table of Contents) の生成を作ることをページ自体にも適用して、ドキュメント自体がサンプルになっている好例。

木構造よりも、ネットワーク構造を好め

のちの江渡さんの『パターン、Wiki、XP ~時を超えた創造の原則』に通じるので、そちらを読むと理解が深まると思います。

ネストしたリストよりも、見出しによる構造化を好め

これは本当にそう。自分も個人ブログの方にエントリにしている。ここではさらに見出しにすべき理由として TOC の生成を挙げている点が秀逸。

koic.hatenablog.com

リストで文章を区切るよりも、空行をあけてPタグでレンダリングせよ

その辺の書籍などを読んでも箇条書き中心で構成されているものはレアだと思う。散文的な箇条書きに頼るだけではない文章を書く力は大事。

安易に項目追加する前に、リオーガナイズを検討せよ

これはちょっと難しかった。問題の背景をうまく掴めていないので (あるいは忘れてしまったようで) 、よく理解できていない。

正規化と重複の均衡点を探せ

同一の文章がページにまたがる物差しについて挙げられていると思う。コンテキストによって補完される内容であれば重複して問題ないと思う。一方でコンテキスト非依存であれば独立したページとして参照されるものだと思っている。DCI (Data Context Interaction) はヒントになりそう。

PREとQUOTEを使い分けよ

コードは PRE を使い、引用は QUOTE を使うで良いと思うが、当時の疑問を分かっていない (私は角谷さん卒業後の後期に参加していた) 。

リオーガナイズのメカニクスを用意せよ

ここで未完となっていて、続きは各人で Wiki を育てていこうといった感じになっていると受け取っている。この記事を種子にして育つと嬉しい。

、、、とここまで書いたあとフェローの角谷さんからコメントをいただく機会がありました。いわくこの項目は「qwik から繋がり 2020年のいま Scrapbox で実現されている」とのことでした。Scrapbox を使った事例の URL をあげておきます。

scrapbox.io

続きは各自の研究に譲ります。

おわりに

現代ではネットワークを辿る方法に限らず全文検索するという手法がより一般的になっていますが、ハイパーテキストハイパーリンクからなる Web ページの文書構造や相関関係というインターネットの基礎概念のひとつについて考える良いきっかけになればと思い発掘してみました。その考え方は Wiki ページに限らず Markdown や AsciiDoc による文書作成にも転用できるでしょう。

以上、3年越し17年ものの復刻作業結果の共有です。個人的にはのちのドキュメントの書き方にも影響を受けており、かつてプレゼンテーションとして起こしたりしました。文書構造に対して新たに考えるきっかけになれば幸いです。

We are going to the Timeless Way of...

f:id:koic:20201014165657p:plain


創業40年の永和システムマネジメントでは一緒にソフトウェア開発のアカシックレコードを刻んで行こうというメンバーを募集しています。

agile.esm.co.jp