This section builds on the information introduced in Getting started with Pipeline and should be treated solely as a reference. For more information on how to use Pipeline syntax in practical examples, refer to the Using a Jenkinsfile section of this chapter. As of version 2.5 of the Pipeline plugin, Pipeline supports two discrete syntaxes which are detailed below. For the pros and cons of each, r

会社でScrapboxを使っている。チームごとやプロジェクトごと、話題や趣味ごとにプロジェクトを作っていて、うちのチームは1年3ヶ月くらい使って3000ページほどに達している。 どんどん書いていたのだけど、最近、どこに何があるかわからなくなってきていた。同僚に、ここの仕様はどうでしたっけ、って何度も聞いてしまうことがあったので、これはまずいと思ってちょっと整理していた。 表記揺れを直す One Fact in One Placeということで、どんどんページをマージしていった。ページを同名にリネームするとマージボタンが出現して押すだけなので楽。 よくみるとスペースの有無によって同じ話題のページが2ページに分かれていたり、略称と正式名称と、「(正式名称)まとめ」の3つにわかれたりしていた。情報を探しているときにはどんどんマージしたりしないので、今回マージするぞと見返せてよかった。 サポート担当

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 初めましてこんにちは。 最近コードレビューの記事書いたら、Excelベースだったことを理由に Qiitaコメントとはてブで徹底的に燃やされたおじさんです。 いやね、僕だって使いたくて使ってるわけではなくてね、 できることなら使いたくないんですよ。 というわけで名誉挽回のために脱Excelできた話、 それも日本の三大悪三大風習に数えられるExcel設計書を抹殺した話を書きます。 (2/25修正：悪は言いすぎました。訂正します。） Growi 最高。 Excel設計書 またの名をExcel方眼紙。 エクセルのセルの縦横を同じくらいの大きさに

私は、昨年度、工業標準化事業に対する貢献により経済産業大臣から表彰を受けました。編集委員会から私に与えられたテーマは、それについて解説せよというものです。しかし、その技術的な内容については既に本ニュースの2004年6月号において「宇宙開発における標準化と情報化」という題名で執筆しています。そこで、今回は、私が標準規格などの文書の作成に力を入れている理由についてお話ししたいと思います。なぜならば、その理由をお話しすることは、「人工衛星のような複雑なシステムをいかに効率的に開発するか」という私のシステム工学的な研究の成果を解説することになるからです。 人工衛星のような複雑なシステムの開発は、必然的に大人数のチームで行うことになるのですが、効率的に開発を行うための一つの原則は、「チーム構成員の誰もが何かしら具体的な作業を担当し、その作業結果を文書などにまとめ、プロジェクトの中で機能させること」だ

これ↓なんですけど、意外と RT や Like が付いてたので、ちゃんと書きますね。 しっかしMicrosoftのドキュメントシステム良く出来てるなー。右のEditボタン押すとGitHubが開いてすぐPR送れる。あちらでマージされれば即サイトに反映される。Contiributorsに自分のアイコンが増えた♪ これはフィードバックするのに「面倒」は理由にできないですぞ。https://t.co/9KhAwhV5PP pic.twitter.com/r46zFUvkEp — あめいぱわーにおまかせろ! (@amay077) 2018年6月12日 このツイは Microsoft の製品やサービスのドキュメントについてなんですが、 Microsoft Docs というポータルがありまして、同社のサービスの多くはここでドキュメント公開されている模様です。 ここで公開されているドキュメント群は、バック

Kaizen Platformでフロントエンド開発をやっているlacoです。 新規アプリケーション開発において、API仕様中心の開発スタイルを検討し、実験的に取り入れました。 本記事ではその概要と効果を紹介します。 API仕様中心開発 API仕様中心開発を取り入れようと思ったきっかけは、2017年のNode学園祭でpika_shiさんが発表した「JSON Schema Centralized Design」です。 JSON Schema Centralized Design - Speaker Deck Kaizen Platformではリモートワークで開発しているメンバーが多く、非同期にコミュニケーションをすることが多いので、生産性を高めるためには互いの作業を待たずに独立して分業できるワークフローが必要でした。 バックエンドAPIの実装を待たないとフロントエンドが実装できないような依存関

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォータ

脚注の使い方に悩む 公私を含め、今までは、記録を取るときに「『例えば』の時は『ex.』、『つまり』の時は、『→』」などと独自のルールで使用していた。特に、脚注（ex.新しい単語が出た場合の意味）等を「すぐ側に書いていいのか」「末尾に書くべきなのか」悩みながら書いていたのも事実だった。 そこで、後で記録を読み返したときに、正式な使い方に則っておくと、読み返したときに「復習しやすい」と思い、まずは、何気なく使いがちな「略語の正式な使い方」について調べてみた。 参考サイト 心理学の論文・レジュメで使えそうな略語（e.x. cf. i.e.など）… - 人力検索はてな 略語の説明が掲載されているはてな人力検索。 http://d.hatena.ne.jp/satomilogy/20090217/1234887577 上記の中からいくつか例を示して説明している。 略語の使用例を整理 使用頻度が高い略

READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ

gitbook TRPGリプレイのテンプレートなるものを作ってみました。 その実装としてとあるCC-BY-NC-SAなライセンスのリプレイを移植してみました 得られた知見 gitbook.com自体で、エディット/CI/デプロイできること、閲覧統計とかあって、環境としてかなりの機能があると思う。(比較対象がないけど) というか、なぜかUSやCanada、FranceからViewがある... Markdownは技術的なほぼプレーンなテキストにはいいけど、装飾とか表現力はちょっと厳しい Asciidocはデフォルトで多少は装飾的にいけるけど、なによりクラスをなんとかいけるのがいい gitbookとgithubの連携はかなり自動化されているけど、要素が(unixコマンド的に)個別の要素として独立しているので、後からのリカバリや変更ができた(ちょっとミスってたので) 作業スタートは、どちら向きでも

要約 mdBookはGitbookにインスパイアされてるRust製ドキュメントビルダー Rust製なのでぶっちぎりに速い、メモリとCPUに優しい 諸々足りない部分はあるが、ある程度運用でカバー出来る 履歴 2016.06.07 mermaid.jsの読み込みと図のレンダリングについての記述を追加 はじめに 社内のドキュメント整備を行うに当たり、まあどうせならバージョン管理しながらテストもしたいし、体系的に纏められるGitbookがいいよね、って話になりました。んで、既存のドキュメントなんかもGitbookにドンドン移行してました。 私は普段、エディターはAtomを利用し、gitbook serveコマンドでwatch & HotReloadをさせながら表示項目を確認しつつ、ツラツラと作成してました。 基本的には push->CI（ビルド&テスト）->デプロイ を繰り返す環境です。 ドキュメ

こんにちは。Akerunエンジニアの @ishturk です。 Akerun Advent Calendarの記事です。 今日は設計書の話です。 設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み（楽しみ）ですね。 最近はまったツールが最高に良かったので紹介させてください。 僕のツールに求める要件は以下です。 編集がカジュアルにできる UMLが書ける。あとから編集できる（画像での貼付けは編集できないのでNG） バージョンの管理ができる 好きになれる（重要） 変遷と pros/cons MS Word pros 良くも悪くもスタンダードなツールですね。 だれでも編集できるのが強みです。 Visioと組み合わせれば、UMLも後から編集可能です cons Visioは標準にするには少々値が張ります。 バイナリ形式なのでバージョン管理はしづらいです。 ページが増えたり画像を貼

ソフトウェア開発の仕事を請けるとき、すぐに開発を始められるような仕様が提示されることは、ほとんどない。発注側がそんなものを用意できるなら、私に依頼せずに、クラウドソーシングを使うほうが費用対効果が高い。仕様を策定するのも込みで、なんなら要件を発掘するところも含めて、仕事が依頼される。 問題解決をしながらのものづくりには、反復的な変更を伴う。顧客に問題ドメインの知識があり、こちらに解決手段の知識がある場合は、互いの共同作業になる。「こういうことですかね？」「ちょっと違うんだよねー。アレをナニする感じで」「こうやれば、いけるかも」「うは、それいい」みたいに。 仕様を記載したファイルを、厳密にキャッチボールできないときには、ひとつのファイルに対して、複数の人間が並行して変更することになる。プログラミングでは diff と merge というツールが活用できる場面である。仕様書を共同で作るとき、そ

これまで少し大きめな機能であれば、コードを書く前にまず仕様や実装の方針をissueのdescriptionにまとめ、それを先にレビューしてもらってから実装にとりかかるということをしていた。最近、その方針をそもそもrepositoryのファイルとして書いて、PullRequestしてレビューしてもらうようにしたら便利だったのでご紹介。 なぜコードを書く前に仕様や実装の方針をレビューするのか 前提としてなぜコードを書く前に仕様や実装の方針をレビューして欲しいのかについて書いておく。これはとにかく手戻りの量を少なくしたいという要求のためである。 実装に取り掛かろうとすると、実装の方針はいくつか思いつくが、どれが一番よいか迷うことはよくある。その場合に誰にも相談せず自分だけで判断し、コードを書いてからPullRequestを送った場合、もしその選択に重大なミスがあった場合全て書きなおさないといけな

はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1