AsyncAPIでつくるMQTTインターフェイス仕様書！ | DevelopersIO
お疲れさまです。サーバーレス開発部の新井です。 今回は、MQTTのインターフェース仕様書を作成するツールAsyncAPIに関する記事です。 弊社岩田のブログでも促されたので頑張って書いていこうかと思います。 参考サイトURL オンラインエディタ ドキュメント生成 コード生成 背景 最近はAWS IoT案件に携わる機会が多く、デバイスの開発者とMQTTのトピックやパラメータの設計をやり取りする機会が増えています。 で、ここのインターフェイスを統一的に管理したいというのがあり、Swaggerみたいな規定フォーマットに沿って記入すればドキュメント作成してくれるようなツールを探したところ、AsyncAPIなるものがあったので、今回はこちらを紹介していきます。 ソースはYAMLで作成して、フォーマットに沿って入力していけば、最終的には上記の様にHTMLファイルベースのドキュメントを生成してくれます。
自己流の手順書フォーマットを公開してみた | DevelopersIO
手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce
テキスト校正くん - Visual Studio Marketplace
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter. テキスト校正くん VS Code上でテキストファイル・Markdownファイル・Re:VIEWファイルの日本語の文章をチェックする拡張機能です。該当のファイルを開いた時、更新した時に自動で校正のチェックを行い、文章内の問題のある箇所をマーキングし問題パネルにエラー内容を表示します。 メールの文章を作成する際やブログ記事の文章を作成する際などに、ご使用いただくと便利です。 ウェブ業界の専門用語を含め、一般的な文章のルールに沿って主に以下のようなチェックを行います。 「ですます」調と「である」調の混在 誤検出の回避のため「である調」の判定は明らかに常体な「〜である」のみとなっています。 ら抜き言葉 二重否定 同じ助詞の連続使用（※初
textlint と VS Code で始める文章校正 - Qiita
はじめに 文章を書くときに、注意して半角文字の両端に半角空白を空けるという手動 lint をよくやっています。 また、日本語の表現や句読点、typo などに注意を払うことも必要です。 そこで、機械的に検出できた方が内容を書くことに集中できるので文章の lint ができる textlint というツールを使っていきます。 同様の検査ツールとして RedPen が存在します。 以下の記事に RedPen と textlint それぞれの立場から文章における問題とその解決についてまとまっているので参考になります。 文書執筆の指南書で解説されている問題点を RedPen で発見する - Qiita 文書執筆の指南書で解説されている問題点を textlint で発見する - Qiita 今回は、リポジトリ内で管理する Markdown ファイルに対して、Visual Studio Code(VS C
RedPen でわかりやすい技術文書を書こう | DevelopersIO
最近はブログを始めマニュアルや仕様書など技術文書を書く機会が多くなってきました。 技術文書はわかりやすさが重要だと思うのですが実際は書けていません。 どうしたらわかりやすい文書が書けるのだろうか？と調べていたら RedPen というツールを見つけたので早速試してみました。 RedPen とは？ RedPen とはプログラマや記者が規約に従って文書を記述するのをサポートしてくれるオープンソースのソフトウェアツールです。 プログラミングが規約に従ってコーディングされているかチェックするように、RedPen は自然言語で記述された入力文書の検査を自動化してくれます。 RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査でき
【コスト削減約30％以上】AsciiDocとGitHubでPDF、HTMLマニュアルのデータを部署をまたいで一元管理 | 事例 | 株式会社ヒューマンサイエンス
【コスト削減約30％以上】AsciiDocとGitHubでPDF、HTMLマニュアルのデータを部署をまたいで一元管理 ヤマハ株式会社様 ヤマハ株式会社グループ 概要 ・設立：1897年10月 ・資本金：285億34百万円 ・従業員数： 連結 20,175人 ・事業内容： 楽器事業、音響機器事業、部品・装置事業 ご利用サービス ・マニュアル作成 ・翻訳 ・AsciidocとGitHubを利用したドキュメント編集＆管理システム構築 導入したマニュアル作成フロー 通常のドキュメントの制作フローで使うシステムやツール類を、各種オープンソースソフトウェア（ATOM/RedPen）やGitHub、SourceTreeなどIT分野に馴染みのあるツール類に代替しました。 各工程のデモ動画 1. テキストエディタATOMでAsciiDocを編集し、GitHubでデータを管理する手順です。 2. AsciiD
脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ - Qiita
asciidocとは asciidocはMarkdownなどのような軽量マークアップ言語の一つで、Webページなどをプレーンテキストで記述することができる(拡張子は.adoc) asciidocを使うようになった経緯 これまではWordで機能仕様書とか書いていたが、Wordは重い、変更場所が分からない、複数人同時に修正とか面倒で、いい加減Wordを使うのは止めたくなった なので軽量マークアップ言語にしよう、一番メジャー？なMarkdownにしたら、以下の制約とかでいくらなんでもイマイチ。。 表でセルの結合ができない 表のセル内で箇条書きができない 目次が作れない 文字に色がつけられない 上記に対応しようとすると、プラグインやらMarkdown亜種がいろいろ。。 そこで、Markdownより表現方法が豊富なasciidocを使用し、実際に使って、特徴・課題を挙げてみた。 asciidocto
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜Anno Takahiro
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
テレワークで始めたドキュメント駆動業務｜Dentsu Digital Tech Blog
こんにちは。電通デジタルでEMをしている河内です。エンジニアにおける採用・評価、スクラムマスターなどを担当しています。今回はすこし実装プラクティスから離れた話題になりますがお付き合いくださいませ。 弊社もご多分に漏れず完全テレワークを実施しており、かれこれ4か月が経ちます。その中で見えてきた課題とエンジニアチームとしてどう対峙したか、そしてそこで得た気づきを綴っていきたいと思います。この内容は、過去に開催したオンラインイベントでお話した内容になります。 テレワーク環境で私たちのエンジニア部門で急務と感じた課題テレワークが開始された2月後半、プログラミングやシステム開発プロジェクトを生業とする私たちの部では「リモート？全然OK。支障無いっす。」とタカを括っておりました。しかし開始されて間もなく、やっぱり慣れていない事が判明・・・。テレワークを経験されている読者の多くの方が感じていることと同様
AsciiDoc cheatsheet
This is a cheatsheet for AsciiDoc - “Text based document generation” script. The cheatsheet available for different AsciiDoc versions (because of some markup syntax changes) and using different css styles. Here is list with all available cheatsheets for different AsciiDoc version and using different css styles (GitHub included).
AsciiDoc入門 - Qiita
AsciiDocとは AsciiDocはMarkdownなどのような軽量マークアップ言語の一つです。 利用例 Pro Git book - Github オライリーの書籍 Clojure Cookbook - Github Programming Scala Mastering Bitcoin - Github Open Government - Github O’Reilly Atlas Neo4j documentation - Github Git User's Manual なぜAsciiDocを使うのか 表現力と可読性 技術文書を書く場合HTMLは汎用性が高いが可読性が低い、一方Markdownは可読性が高いがテーブル記法がないなど表現力が乏しい。 AsciiDocは可読性が高く表現力もある程度高いので、技術文書等を書くには最適である。 表現力：HTML > AsciiDoc >
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
http://www.methods.co.nz/asciidoc/