Markdown を拡張する MDX はドキュメント作成の新たな可能性？
この記事は、技術書典 11 で頒布中の「Vivliostyle で本を作ろう vol. 5」から抜粋した記事です。ご興味ありましたら、Vivliostyle を使って組版された本誌もぜひお買い求めください！ また、この記事以外の内容もすべて Vivliostyle 公式サイトで無料公開中です。 技術書やドキュメントを執筆する際、あなたはどのような形式で文章を書きますか？ 最近ではもっぱら Markdown で書かれることが多いですが、この Markdown を拡張するポテンシャルを持つお気に入りの OSS プロジェクト「MDX」を紹介します。 MDX = Markdown + JSX MDX の名前の由来は Markdown + JSX なので、MDX を理解するためにはまず JSX について知る必要があります。 JSX とは JavaScript の拡張構文の一つで、元々 React の
Amazon S3 へのファイルアップロードで POST Policy を使うと、かゆいところに手が届くかもしれない - カミナシ エンジニアブログ
はじめに こんにちは。カミナシでソフトウェアエンジニアをしている佐藤です。 みなさんは、アプリケーションのフロントエンドから、Amazon S3 にファイルをアップロードするときに、どのような方法を用いているでしょうか？ 「バックエンドのサーバーにファイルを送信し、バックエンドのサーバー経由で S3 にアップロードしている」「Presigned URL を払い出して、フロントエンドから直接 PUT している」など、いくつかの方法があると思います。 弊社で提供しているサービス「カミナシレポート」でも、用途に応じて上記の方法を使い分けて S3 へのファイルのアップロードを行っています。 特に、Presigned URL は、手軽に利用できる上に、バックエンドのサーバーの負荷やレイテンシーの削減といったメリットも大きく、重宝しています。 一方で、その手軽さの反面、アップロードに際して様々な制約を
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
"レガシー"と言われないためのJavaScript再入門
追記: 10/11 ハテブでバズっているようで、色々指摘があったので追記 getElement*は動作が早いのでIDやクラス名が自明の場合はgetElement*を使う方がいいと言う意見もあり、また、ページの表示で大量に呼び出されるわけではないからボトルネックにはならないと言う意見もある。 getElement*で返されるオブジェクトは動的な変化に対応しており、querySelector*は動的な変化に対応していないため、場合によってはgetElement*を使うといい。このサイトで遊んでみよう。 https://ja.javascript.info/searching-elements-dom#ref-263 for await ... ofは非推奨なので Promise.allを現代的な書き方にした 顧客先のブラウザが古い場合も考慮して、あえてレガシーな書き方もする場合があるらしい。現
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
契約書の差分比較をGPT-3を使って自動化する - Qiita
こんにちは！逆瀬川 ( https://twitter.com/gyakuse ) です！ 今日は契約書の更新差分の比較をGPT-3とGoogle Document AIを使ってやってみたいと思います。 概要 異なるバージョンの契約書をPDF解析システムとGPT-3を使って自動的に比較し、リスクなどの検討も自動で出力する仕組みを作る。 Colab 使い方 Document AIの準備 (作成方法など詳しくは後述) Google CloudのDocument AIでプロセッサを作成する プロセッサ一覧から作成したプロセッサを選び、予測エンドポイントをコピーする https://console.cloud.google.com/ai/document-ai/processors json形式のAPIキーファイルをダウンロードしておく OpenAI APIキーの準備 すべてのセルを実行 比較した
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
VSCode + Markdownでスライドや書籍も書いちゃおう！ - Qiita
はじめに Markdownって便利ですよね？ README.md、PR や Issue の本文やコメント、Qiita や Zenn はもちろん、Google Docs や Trello や Notion や Jupyter Notebook でも使えるみたいです。もっといろいろな文書を Markdown で書ければいいのになあ、あらゆる文書のソースコードを Markdown にできればいいのになあ。 さあ、Markdown の可能性を広げましょう！ 本記事では「スライド」と「(電子)書籍」をMarkdownで書く方法をご紹介したいと思います。もちろん、VSCodeでMarkdownを効率よく便利に書いていくためのチップスもご紹介していきますよ。 ご参考スライド VS Code Conference Japan 2021 で発表した際の以下スライドもご参照ください。 もちろんこのスライドもV
設計書・仕様書のレビュー方法を定めたJIS規格登場 チェック体制を標準化しやすく
経済産業省は11月22日、システム開発時に使う設計書・仕様書などの「作業生産物」のレビュー工程についてJIS規格を制定したと発表した。仕様書などの見直し方や観点などを規格化し、ソフトウェアの品質向上や開発の効率化を促す。 「JIS X 20246」は、設計書・仕様書の見直し作業を「計画作業」「レビューの立ち上げ」「個々人のレビュー」「要検討項目の共有および分析」「修正作業および報告作業」の順に整理し、実行するべきタスクや手順を規定するもの。システム開発や試験、保守などの場面で作るあらゆる仕様書に適用可能。 レビューの曖昧さをなくすため、「目的」「役割」などのレビューの観点10種、「執筆者確認」「同僚との机上確認」などのレビュー手法9種を定めた。JIS制定により、組織や個人のノウハウに依存することなく一定水準のレビューができるようになり、ソフトウェアなどの制作物の品質向上につながるとしている
自己流の手順書フォーマットを公開してみた | DevelopersIO
手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce
音を操るWeb技術 - Web Audio API入門 - ICS MEDIA
Webにおける表現はどんどん進化しています。Webサイトには当然のように動画が埋め込まれるようになり、CSSやSVG、canvasでのさまざまな表現が頻繁に見られるようになりました。さらにAR、VRといった表現も台頭し筆者も毎日ワクワクしながらインターネットの海を泳いでいます。 その中であまりメジャーではないと感じるのは「音」による表現です。もちろん音を用いた素晴らしいWebサイトはたくさんありますが、環境の制約が視覚表現以上に大きいため多くは見られないのでしょう。 とはいえ、音と視覚表現を組み合わせることによって表現できる世界観、インタラクション、その他諸々は計り知れないと筆者は思っています。今後オーディオなどの技術の進歩によって上記で述べた制約も乗り越えられるようになるかもしれません。時代を先どりしたい読者に向けて、今回の記事ではWebで音を扱う技術Web Audio APIについてお
Scrapbox - A new style of team wiki
Effortless ideation.Type brackets around an `[idea]` to create a new link or see auto-complete results. You can instantly click to jump to a new page and keep typing ideas. Compound organization.As you add more pages your ideas get more and more organized. By adding a single link you can see new connections to dozens of related pages. Frictionless focus.Paste links to embed. Share code with syntax
すげー！！！AIの今北産業、超優秀！！！
AIが長文を3行ぐらいにギュッとまとめてくれるエンジン「IMAKITA」を使ってみた - GIGAZINE http://b.hatena.ne.jp/entry/s/gigazine.net/news/20181211-imakita/IMAKITA Document Squeezer https://www.qhapaq.org/imakita/ AIで長文を要約してくれるWebサービスが話題だったから、この増田を入れてみた。 その結果がこれ。 Summary of the Documentラーメンをすすって食べる人のことが大嫌いです。 そもそも時代をさかのぼっても、蕎麦などの麺類以外は音を立てずに食べるのが常識です。 もう時代は変わって音をたてて食べる人のほうが少なくなってきてることに気がついてほしいです。 音をたてないように気をつけて食べてでる音は仕方ないと思っています。 音をたて
Firebase Cloud Firestoreを使って、車の草耐久レースを少し改善した話。 - Qiita
普段の業務では、iOSやAlexaのスキル開発を中心にやっていますが、趣味では愛車でサーキットへ行ったり、ジムカーナを楽しんだりしています。（自称アウトドア) その延長線上で、とあるアプリを作りかなり革新的なことを実現したので簡単にまとめます。 そもそも草レースって？ 一般的に車のレースっていうとまず先にF1であったりSUPER GT選手権やスーパー耐久などが思い浮かぶ方も多いかもしれません。これらに関しては、プロドライバーであったり自動車メーカー、ワークスなどがガチで争うマジモンのレースです。 ただ、そんなプロのレースの他にアマチュアのレースの世界があります。それが草レース。要は車趣味の愛好家がガチンコで楽しむ趣味のレースと言えばわかりやすいでしょうか。 今回参加した草レース 草レースの中でもいくつかのタイプはあります。１つの枠でLapTimeを極めるものや周回数を極めるものであったり。
ESDocという(多分)モダンなドキュメンテーションツールの紹介 - maru source
こんにちは丸山@h13i32maruです。 僕は2015年からESDoc*1というJavaScript向けのドキュメンテーションツールを開発しています。 https://esdoc.org https://github.com/esdoc/esdoc Star 最初のリリースから2年、昨日ようやくv1.0をリリースできました🎉 いやー、ここまで長かったです。今ではRxJSやSketchAPIなど、様々なツールで使用されています。 この2年間、ESDocは2つのゴールを目指して開発してきました。 ドキュメントの作成・メンテナンスを快適にする（ドキュメントを書くの楽しい！という状態） ソフトウェアの使い方を簡単に理解できるドキュメントを作成する（ソースコード読まなくても大丈夫！という状態） この2つを満たすためにESDocは色々な機能を提供しています。 今日はそれらの機能の中でも(多分)モダ
脱ファイルサーバ！！個人でも会社でも使えるOSSのドキュメント管理システム！その名も「Alfresco」！
脱ファイルサーバ！！個人でも会社でも使えるOSSのドキュメント管理システム！その名も「Alfresco」！CMSインフラOSSAlfresco文書管理 はじめに ファイルサーバって重いし、ファイル探すの大変だし、ファイル名だけだとどれが目的のファイルかわからないし。。。 と感じた経験はありませんか？ 私も強く感じていて、いい感じのドキュメント管理システムないのかなと探していました。 DropBoxやOwnCloudも候補としてあったのですが、いまいち響かず。。 そんな中出会ったのが、「Alfresco」！ この出会いをみなさんに共有すべく、記事を書かせていただきました。 インストール作業は以下の記事を参考にしてください。 Alfrescoのインストール作業をコマンド単位で丁寧に記載します Alfrescoとは？ 参考:Alfresco公式ホームページ AlfrescoはCMS（コンテンツマ
The Swift Programming Language 日本語訳 | スタジオガラゴ
1.1. Swift について | Swift Published on 2015年12月10日 1.2. Swift ツアー | Swift Published on 2015年12月11日 1.2.1. シンプルな値 | Swift ツアー | Swift Published on 2015年12月12日 1.2.2. 制御フロー | Swift ツアー | Swift Published on 2015年12月13日 1.2.3. 関数とクロージャ | Swift ツアー | Swift Published on 2015年12月14日 1.2.4. オブジェクトとクラス | Swift ツアー | Swift Published on 2015年12月15日 1.2.5. 列挙型と構造体 | Swift ツアー | Swift Published on 2015年12月16日 1.
swaggerでAPIドキュメントを書いたらめっちゃはかどった話 - kaz29
Swaggerは、REST APIの仕様とそれに関連するツール群の総称です。REST APIの仕様を定義したJSONファイル(Swagger Spec)を軸に以下のようなツールから構成されています。 Swagger UI - Swagger Spec から動的にAPIドキュメントを生成するツール Swagger Editor - Swagger Specのエディタ Swagger Codegen - Swagger Specからクライアントのコードを生成するツール 最近では、Open API InitiativeがAPIの記述のためにSwaggerを採用して話題になりました。 www.publickey1.jp APIドキュメントのメンテは結構面倒 一般的にAPIの仕様書は、古くはExcel/Wordなどを使ったり、最近ではWikiやMarkdown形式で記述したりなどプロジェクトによって
デスクトップを録画するアプリを書いた - Qiita
手軽にデスクトップ（or ウィンドウ）を録画できるアプリが欲しかった Photon を使ってみたかった Electron 楽しい 以上の動機で書いてみました。Rec って名前です（てきとー）。レポジトリはこちら。Mac であればバイナリを置いてあります。Windows は試していないです。 使い方 アプリを起動するとデスクトップとウィンドウの一覧がサイドバーに並ぶので、録画したいものをクリックしてから、カメラアイコンをクリックで録画開始です。止めるときは停止アイコンですね。仮想デスクトップをお使いの場合は、対象のデスクトップにアプリを移動して、右上のリフレッシュボタンをクリックです。 停止アイコンをクリックで録画された webm がダウンロードできますので、あとはご自由にどうぞ。 中身 Electron v0.36.0 から desktopCapturer モジュールが使えるようになりまし
SwiftでHTMLを構文解析して、UITableViewにマッピングする方法 - Qiita
最後に今回のサンプルコードをGitHubにあげております。 (あまり綺麗なコードじゃないかもしれないですが、参考程度にしてもらえればと思います) なぜWebViewを使わずに、UITableViewにマッピングするのか 理由はデザインを統一させたいというのが一番です。 あとはOnoの作者であるMatttさんが復活したということで、 今回Onoについてご紹介したかったのが大きいです(-∀-) この記事は、マッピング方法を記載しておりますが、 HTMLの構文解析だけを行いたい場合でも、参考になると思います。 実装方法 ライブラリ導入 https://github.com/mattt/Ono#podfile Onoをプロジェクトに導入します。 動作確認 以下のようにOnoをImportして、利用することが出来れば問題なく導入できている思います。 import Ono <省略> let docum
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
