はじめに 私の職場では、WebAPIの仕様書をWordで書く習慣があったのですが、2018年頃にSwaggerで書くように切り替わったので、そのように変化した経緯を書きます。 何かの参考になれば幸いです。 ちなみに、こちらの記事と同じ職場です。 Wordな職場にMarkdownを定着させるためにやった４つのこと Swaggerとは？ Swaggerとは、REST APIの仕様を定義するためのフォーマットです。その周辺技術も含めて、Swaggerと呼ばれます。以下の記事が非常に参考になりますので、詳細を知りたい方はご参照ください。 Swaggerの概要をまとめてみた。 Swagger 導入失敗 2016年頃のある日、上司から「世の中にはSwaggerというものがあるらしい。調べてもらえる？」と指示されました。 調べてみたところ、Swaggerがあれば、WebAPIのドキュメントサイトも作れる

字下げ.iconMarkdownというマークアップ言語がエンジニア界隈で広く使われている。もともとはHTMLをもっと簡単に記述したいという意図で開発されたものだそうで、<h1>タイトル</h1>と書くかわりに# タイトルと書けたりするので、記述が少し簡単になるというメリットがある。太字(<b>)やリスト(<ul><li>)なども簡単に書ける。 字下げ.iconMarkdownに慣れたエンジニアがよく「何故ScrapboxはMarkdownを採用しないんだ」と言ってくる。「Markdownを採用しないとか馬鹿じゃないの?」とまで言う人もいる。こういう人々は完全にMarkdown脳というか、自分がタマタマ慣れているものがサイコーだと考えているだけに思える。 字下げ.iconScrapboxのようなWikiで一番大事なのはページ間リンクの記述であり、ここに[...]という単純な記法を使っているた

MOONGIFTはオープンソース・ソフトウェアを紹介するブログです。2021年07月16日で更新停止しました MarkdownファイルからPDFにして欲しいという話は良く聞きます。この時便利なのがPandocなどのツールであったり、Markdownエディタによっては標準でサポートしている場合もあります。macOSであれば印刷機能でPDFにする手もあります。 今回はその逆です。PDF To MarkdownはなんとPDFを読み込んでMarkdownに変換するソフトウェアです。 PDF To Markdownの使い方 一例です。こんなPDFがあります。 Markdownへの変換結果です。なんと日本語が通ります。 別な例です。文章は大抵リストになってしまうようです。 PDF To Markdownは文章の整形などはあまり期待できません。殆どリストで書き出すだけのようです。しかし、そもそもテキスト

はじめに pandocを使ってmarkdownをword文書に変換する方法はよく紹介されていますが、 過去の資産をmarkdown化するなどの動機で逆（docx→md）を実行したくなるときもあります。書式など色々設定していると中々きれいに変換できなかったのですが、pandocのオプションを適切に指定するとある程度うまくいくようです。 docx→md pandocでdocxを変換する際、出力フォーマット指定でraw_html,native_divs,native_spansを抑止すればよいようです。 参考：http://stackoverflow.com/questions/35807092 画像ファイル 本文に画像を含む場合、そのままではmedia/image1.wmfなどのリンクがあるだけで、画像ファイル自体は出力されません。以下の手順で、mediaフォルダをdocxファイルから抽出しま

こんにちは、QAエンジニアの井上恵一です。好きな飲み物は一番搾りと韃靼そば茶です。 初回からニッチなネタではありますが、昨年入社した直後に行った、 iPad アプリのテスト仕様書の管理方法を見直したときの話を紹介しようと思います。 見直しのきっかけ トレタは飲食店向けの予約/顧客台帳アプリです。だれでもかんたんに使いこなせるシンプルさを追求してはいますが、製品の進化に伴ってそのテストケース数はすでに数千という単位にまで膨れあがっています。 製品の品質を安定させるためには、テストの内容自体をブラッシュアップすることが重要なのは言うまでもありません。ただ、安定した製品を永続的に提供していくためには、それに加えて、膨大なテストケースを効率よくメンテナンスし続けるためのプロセス作りも欠かせません。 入社のタイミングでトレタのテスト設計を担当することになったので、テストケースの管理方法についてもいち

電子書籍開発環境 Markdownで書く電子書籍開発環境というスライドで、GitBookとMarkdownで技術書(電子書籍)を書く話を紹介しました。 文章はtextlintで、コードはESLintとテストでチェックして、サンプルコードに対してテストを書けるプロジェクト構造について書かれています。 どのように表記揺れなどやコードの間違いを防ぎながら、書籍を開発していくかについて書いているので詳しくは上記のスライドを見て下さい。(スライドの下へスクロールすると文章版が載ってます) スターターキット 上記の設定をすぐに使えるようにスターターキット的なものを作りました。 azu/gitbook-starter-kit 実際にこのgitbook-starter-kitを電子書籍とした時の表示は以下で見ることができます。 GitBook Starter Kit - GitBook インストール 利用

Emacsにはバージョン24からewwと呼ばれるWebブラウザ機能が同梱されるようになった。これを利用して、EPUBのような電子書籍フォーマットやdocx(Microsoft Word)のようなリッチテキスト、Markdownやorg-mode、Textile、などの軽量マークアップ言語などのいろんなアレをEmacsで読めるようにする。 つまり、「おめーREADMEファイルをreStructuredTextとかAsciiDocとかTextileとかよくわかんねーフォーマットで書いてんじゃねーよ読めねーだろ」ってときにも安心ですね☆ 追記 @10sr さんの指摘通り、AsciiDocはinputには利用できませんでした。残念… 用意するもの Emacs 24.4+ (libxml必須) Pandoc (Windowsでも動くらしい) http://pandoc.org/installing.

社内研修の準備でストレングスファインダーというのを受けてみた結果「適応性・最上志向・戦略性・収集心・着想」となったtanakaです。 社内の情報共有ツールとしてGitLabを使っている話を紹介します。 社内での技術情報共有って難しいですよね。それ自体で会社の売上や自分の給料が増えるわけではありませんし、でもやったほうがいいと大体の人は思っているはずです。 シーブレインでは入社した当時は社内サーバにMTOSを用意して情報共有ブログとして使っていました。あまり使われなくなっていまから3年前に社外サーバにWordPressサイトを用意して情報共有ツールとして使うようになりました。14ヶ月で450記事、月平均32記事とそこそこ使われていましたが、情報共有ツールとして以下のような問題を抱えていました 記事はMarkdownで書けるようプラグインをインストールしていたが、コメントはMarkdownで書

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

(11/07) AppleがApple IntelligendeのためにM4チップ搭載のAIサーバーを台湾に設置予定 (11/07) コスパ最強となったM4 Mac miniを最安値で購入する方法 (11/05) 次のM3チップiPad Airは90Hzの固定リフレッシュレートのLCDディスプレイが搭載か (11/05) オーディオブック聴き放題Audibleが3ヶ月99円で利用できるキャンペーン！（12/6まで） (11/05) M5チップ搭載Vision Proが2025年に発売、低価格モデルは発売延期で2027年以降に (11/04) Amazon冬支度セール！Echo Buds 2やFire HD 8タブレット、防犯カメラRingなどが特価に（11/12まで） (11/03) M4 Maxのベンチマーク結果が公開、M3 Max比で最大24%もパフォーマンス向上 (11/03) 画像

はじめに Webサービスやアプリを企画したり、立ち上げたりする際にプロトタイピングツールや、ExcelやPowerpoint、Illustraterなどを駆使した謎のファイルで画面遷移図を描くことがある。 こういう図を元に仕様を決めて行って、サービスを作っていくのは以下の点で困る。 画面遷移図が保守されない。 書くのが非常に面倒くさい ユーザーのモチベーションの流れが追いづらく、見た目ばかりに注目してしまうものになりがち マシンリーダブル(ソフトウェアで構造を取り出せない)でない。 このような欠点があってどうにも扱いづらい。 そんなわけで、markdown風のテキストから簡単に画面遷移図を描けないかなとコンパイラを作成し、次にそれをインタラクティブに編集できるエディタを作成した。 UI Flows図について 画面遷移図的なものを書く際に、僕が個人的につかっていた表現方法として、UI Flo

最近はブログを始めマニュアルや仕様書など技術文書を書く機会が多くなってきました。 技術文書はわかりやすさが重要だと思うのですが実際は書けていません。 どうしたらわかりやすい文書が書けるのだろうか？と調べていたら RedPen というツールを見つけたので早速試してみました。 RedPen とは？ RedPen とはプログラマや記者が規約に従って文書を記述するのをサポートしてくれるオープンソースのソフトウェアツールです。 プログラミングが規約に従ってコーディングされているかチェックするように、RedPen は自然言語で記述された入力文書の検査を自動化してくれます。 RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査でき

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article?

はじめに あるプロジェクトで仕様書をそれなりのクオリティで書く必要が出てきました。Markdownで書きたいなーとか履歴管理したいなーと思っていたので、GitHubで管理してGitBookとしてドキュメント化することに決めました。 内容 GitBookとは？ 「Markdownで簡単に電子書籍が作れるよ」というものです。GitHubのレポジトリを指定すると勝手にホスティングしてくれる gitbook.com というサービスの他に、OSSでも公開されているので自前の構築も可能です。 gitbook.com を使えばかなり楽が出来ますが、以下の2点が問題点としてありました。 確認した時点で日本語ディレクトリだと正常に動かなかった ほかの人(主にクライアント)に見せるためにprivateで構築してコラボレーターに追加するのが面倒 そこで今回はOSS版のGitBookを活用し、自前で構築しました。

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article?

gravizoというサービスを利用すればMarkdownの中にGraphviz互換のグラフが埋め込める模様。 使用例 といった形式で表示するグラフを指定する。 以下、公式HPからの抜粋。 ソース: ![Alt text](http://g.gravizo.com/g? digraph G { aize ="4,4"; main [shape=box]; main -> parse [weight=8]; parse -> execute; main -> init [style=dotted]; main -> cleanup; execute -> { make_string; printf} init -> make_string; edge [color=red]; main -> print

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8" /> <link rel="stylesheet" type="text/css" href="./github-markdown.css" /> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-alpha1/jquery.min.js"></script> <script src="https://cdnjs.cloudflare.

フローチャートやシーケンス図をマークダウンで記述が可能なエディタ Sunny Place Editor(Early Access版：0.1.0 Honolulu)を公開しました。 片手間でやっているので、まだまだ 残念なところだらけ なのですが、使えなくもないのでEarly Access版(Honolulu)を公開することにしました。現在はMac版のみです。 **Windows版はもう少し待ってください。**ただ、何ヶ月も待たせはしない予定。 0.使い方 アプリダウンロードは以下からどうぞ。 Sunny Place Editor ダウンロードしたファイルに同梱のREADME_ja.mdをエディタから開いてみてください。 ちなみに、こんなことができます。 1.GitHub形式のマークダウンが利用できる。 2.フローチャートやシーケンス図がかける。 3.アンカーの自動埋め込み（オリジナル機能）

Forget building your own custom docs platform. With GitBook you get beautiful documentation for your users, and a branch-based Git workflow for your team.