本連載では、VSCodeにフォーカスし、基本的な使い方から拡張機能の活用、そして本格的な開発現場での利用を想定した高度な機能までを紹介していくことで、読者がVSCodeマスターになるお手伝いをします。VSCodeは、プログラミング以外の用途にも使えます。第10回では、VSCodeをドキュメント作成のためのテキストエディタ、Markdownエディタとして使う方法を紹介します。 はじめに Microsoftの提供するVisual Studio Code（VSCode）は、2015年の最初のリリースから、今では開発用エディタの定番の座を占めるまでになりました。これには、無償で使えることも大きいですが、何よりエディタとしての使いやすさ、そしてさまざまな拡張機能によっていくらでも使い勝手を向上させたり、利用の領域を拡げたりできることも大きいでしょう。 本連載では、このVSCodeにフォーカスし、基本
AIでユニットテストを自動生成。リファクタリング、ドキュメントの生成、バグの検出なども行う「Refraction」登場
AIでユニットテストを自動生成。リファクタリング、ドキュメントの生成、バグの検出なども行う「Refraction」登場 ChatGPTに代表される自然言語やプログラミング言語のコードを理解するAIを用いてコーディングの支援を行うツールがまた新たに登場しました。 Refractionは、示されたコードから自動的にユニットテストを生成するほか、コードのリファクタリング、ドキュメントの生成、バグの検出などを行います。 Updates! https://t.co/9otFTI7nh0 is now https://t.co/MtN5JgnetI. Building out many utilities. You can... Generate unit tests Generate inline documentation Refactor your code Added a $5 / month
画像・PDF・TXT・メールなどの中身を読み取って検索できるようにするオープンソースのドキュメント整理ツール「Teedy」レビュー
Teedyはさまざまな種類のファイルの中身を読み取って検索できる状態にしてくれるドキュメント整理ツールです。受信したメールを自動で取り込む設定もできるとのことなので、実際にセルフホストして使い勝手を確かめてみました。 sismics/docs: Lightweight document management system packed with all the features you can expect from big expensive solutions https://github.com/sismics/docs TeedyのインストールにDockerを利用するので、下記のリンクから自分の環境に合った方法でDockerをインストールします。 Install Docker Engine | Docker Documentation https://docs.docker.com
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023
［速報］GitHub、組織のコードやドキュメントを学習しカスタマイズやファインチューニングが可能な「Copilot Enterprise」発表。GitHub Universe 2023 GitHubの年次イベント「GitHub Universe 2023」が米サンフランシスコで開幕しました。 1日目の基調講演で、Copilotが組織のコードやドキュメントを学習することで、カスタマイズやファインチューニングが可能になる「GitHub Enterprise」が発表されました。 Copilot Enterpriseは、外部に公開されていない組織内のコードやドキュメント、プルリクエストなどを追加でCopilotに学習させることで、組織内のコードベースに基づいたCopilotによるコードの生成や、Copilot Chatでの質問に対する回答が可能になるというものです。 さらに言語モデルそのものを組織
git-schemlexとddl-makerを使ったDB migrationの紹介 / git-schemalex and ddl-maker migration #golangtokyo
DMM Groupのエンジニアが、Goを活用したプロダクト事例やトレンド、現場のリアルを話すイベント「DMM.go」。2回目の今回は、DMM.com プラットフォーム事業本部 エンジニアの本田雄亮氏が、Goaを使ってAPIサーバーを作る方法について紹介しました。関連資料はこちら。 手作業のドキュメントとコードとは乖離する 本田雄亮氏：今回、「Goaを使ってAPIサーバー開発してみた」というタイトルでお話ししたいなと思います。 まず自己紹介です。プラットフォーム部というところで基盤システムの開発をしています。バックエンドのエンジニアです。名前は本田です。興味あるのは、Goとかアーキテクチャ。DDDとかがけっこう好きなので、もし懇親会に参加される方がおられたら、Goaだけの話じゃなくて、Go全般だったりアーキテクチャ、DDDまわりでもお話できたらなと思っています。 さっそくメインテーマのGoa
Notionでドキュメントを書いてる。ドキュメントは書く、共有する、読むなどユーザーそれぞれ色々なシナリオがあり、そのシナリオそれぞれでつらみがある。 Notionに限らずすべてのサービスは使っていればつらいところはあると思っていて、つらいとはいえNotionから別のドキュメント管理サービスに乗り換えたいという気持ちは全くなく何がつらいのか考えNotionでなにか出来ることはないか考えたり、つらみを共有することで知見を得たい。 検索がつらい フロー型とストック型の情報が入り乱れる 検索をする時はストック型の情報を探すことが多い。例えば、リリース作業手順ドキュメントを探したいときに「リリース 作業 手順」で検索するけど日報や議事録などは検索から除外したい。 Notionの検索には、FilterでPageの指定が出来るのでそれを駆使するしかない。Pageの指定をした場合、Pageの配下は検索対
はじめまして。損害保険ジャパン株式会社 DX推進部の眞方です。普段はリードエンジニアとして、新しいサービスのアーキテクチャ検討からローンチまでの作業や、新規技術を用いたアプリのプロトタイプ実装などを行なっています。 弊社では、LLM（Large Language Models）を活用したアプリケーションの開発を積極的に検討し、既に社内でいくつかのプロトタイプをローンチしています。 本記事では、その最も一般的？なユースケースの一つとも言えるRAG（Retrieval Augmented Generative）の構築において、ドキュメント検索精度の向上にどのように取り組んだ内容の概要を紹介させていただきます。実際の詳細な手法および結果については、別記事（実践編）で解説予定です。 はじめに RAGとは？ この記事を読まれている方の中にはご存知の方も多いでしょうが、RAGとはRetrieval A
2021年6月2日に行われたSendai Frontend Meetup #6で使用したスライドです。 GitHub サンプルコード https://github.com/KanDai/openapi-sample ReDocで生成されたドキュメント https://kandai.github.io/openapi-sample/ About Swagger Specification https://swagger.io/docs/specification/about/ Swagger Editor https://editor.swagger.io/ Stoplight Studio https://stoplight.io/api-design/ Swagger UI https://petstore.swagger.io/ Redoc https://github.com/Red
インフラの環境構築を行ったときに、はい、環境です、と接続情報だけ顧客に提供したところで、そのまま受け取ってくれることはない。 ドキュメントはないんですか？。 何を作ったかを示すドキュメントとセットで初めて、プロにお金を払って仕事をしてもらった気持ちになる。今でも、ドキュメントを残せ、ドキュメントがないと今どうなっているかがわからなくなる、常に更新して最新にしよう、そんな掛け声は健在である。 このドキュメント、年々複雑さが増していると思う。というのも、IT関連のソフトウェアにしろクラウドにしろ、機能は増えるばかりだからだ。かつ、設定自体は年々洗練されており、デフォルト値で動くことも多い。たくさんの設定項目があるが、設定するのはほんの一部分である。 ドキュメントに何を残すべきか。設定値全てをドキュメントに書き込もうものなら莫大な量になる。一方で変更したものは少ししかない。このギャップが激しくな
「サポートを当初発表よりも長く延長延長延長延長延長延長延長延長延長延長延長」 AWS公式ドキュメントの誤記が「破壊力高い」と話題
一連の誤記は、原語（英語）版からの機械翻訳が原因とみられる。AWS公式ドキュメントの多くには「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します」との注意書きがある。 つまり日本語のドキュメントはあくまで機械翻訳なので、参考程度の情報にすぎないわけだ。冒頭のような派手な誤記は確認し次第修正するが、正確な情報が速やかに必要なら原語版を読んでほしい、ということだろう。 誤記を見つけた人たちも承知しているようで、SNSではおおむね“笑えるミス”として受け止められている様子だ。一方で、中には「企業ならちゃんとしてほしい」とする声もあった。 関連記事 “AWS公式サイト風”にカップ麺を紹介する画像が話題 分かりにくい説明文をそれっぽく再現 「もはやAWS文学」 カップ麺の特徴をAWSの公式サイト風に説明した画像が「もはやAWS文
万能ドキュメントサービス「Notion」をさらに活用できるWebサービス・Tipsを徹底解説！ - paiza times
どうも、まさとらん（@0310lan）です！ 今回は、多彩なドキュメントを作成できる万能サービスとして人気の「Notion」を、もっと便利に活用できるWebサービスやTipsをご紹介していきます。 Notion単体でもさまざまなことができますが、Webサービスを組み合わせることでデータの可視化やインタラクティブ要素の追加など多彩なことが実現できるので、まさに無限の可能性を手に入れられると言っても過言ではありません。 「Notion」を利用中の人もそうでない方も含めて、ドキュメントサービスにご興味ある方はぜひ参考にしてみてください！ ■「Notion」とは まず最初に「Notion」をまだ使ったことがない人に向けて、どのようなサービスなのか概要を少し解説しておきます。 【 Notion 】 「Notion」はノートやメモなどのドキュメントを作成したり、タスク管理やWikiのようなページを作れ
困った時はドキュメント、どうもかわしんです。最近、諸事情で SQLite のドキュメントを読んでいます。 前回の記事 で紹介した通り SQLite を Rust で再実装しています。おかげさまで 300 を超える Github Star もいただき嬉しいです。 github.com SQLite は全ての仕様が ドキュメント にまとめられているので、そのドキュメントと本家の実装を読み比べながら実装しています。 SQLite を再実装する上で特に以下のドキュメントは役にたちます。これらだけで最小限の SQLite の実装は作れると思います。 Overview Documents > About SQLite いかに SQLite がすごいかを自慢しているドキュメント。使おうとしている人には安心を、再実装しようとする人には絶望を与えてくれます。 Programming Interfaces >
こんにちは。PlayStation 5が一向に買えない@giginetです。普段はモバイル基盤部というところでiOSの基盤開発をしています。 皆さん、行動していますか？我々は日々Webサービス上で様々な行動をしています。サービス開発において、改善に活かすための効率的な行動ログの収集方法はしばしば課題になります。 今回は、サービス開発者がモバイルアプリ上で簡単にログを定義し、分析を行えるログ基盤を導入した事例について紹介します。 行動ログとは何か モバイルアプリの行動ログとは、ユーザーのアプリ上の操作や利用状況を取得、集積するためのものです。 例えば、特定の画面を表示したり、特定のボタンをタップしたり、といったユーザー操作を起点として送信されています。 集められたログは、サービス開発のための分析や実態把握に役立てられます。 最近はFirebase Analyticsなど、PaaSの形態で提供
GitLab的ドキュメント文化を組織にインストールする（実践編:スタートアップMNTSQの事例）｜Anno Takahiro
会社組織にドキュメント文化をインストールすることの有用性や、GitLabのような企業がどのようにドキュメントを運用しているかを、前回記事で書いた（スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ）。今回は、私のいるスタートアップのMNTSQ（モンテスキュー、と読みます）でどのようにそれを実践しているか、実際のところどのような成果が出ているのかについて書いてみたい。 MNTSQでは、当初からドキュメンテーションの重要性を経営メンバー全員で認識しており、社内ドキュメントをGitHub管理でメンテナンスしながら作り上げていくようにしていた。この大枠の仕組みの設計部分は弊社のデザイナーの生谷(@ikutani41)が初期に考案/メンテしたものである。デザイナー視点からこのような仕組みが設計され稼働されることは珍しいと思う。この辺については本人からもどう
新型コロナウイルスの感染爆発を防ぐため、政府が7日に東京など7都府県を対象に緊急事態宣言を発令した。ただ、7日時点で7都府県とも施設の休業要請は出さなかった。一夜明けた8日、街には発令前と変わらぬ姿もみられた。午後1時半 横浜市横浜赤レンガ倉庫は周辺では、カップルや家族などが楽しむ姿が多く見られた。陽光を受けて元気よく花が咲く庭園前で、半袖姿の女性(28)は生後4ヶ月の子供を乗せたベビーカーを
APIの開発は複雑でコストがかかる可能性があり、頻繁に更新されることからドキュメントを整備するのも難しい。APIの設計、開発、ドキュメントの整備、管理にまつわる課題と効率さの問題に対処するアプローチが、RESTful API Modeling Language（RAML：RESTful APIモデリング言語）だ。 RAMLコードを使えば、開発者はAPIの動作を説明する仕様を策定してからそのAPIをデプロイするまでのAPIライフサイクルを管理することができる。 RAMLとは RAMLは、RESTful APIを記述することを目的とするオープンソースの記述言語だ。2013年、米国のIT自動化および統合ベンダーであるMuleSoftを中心とする数社の企業によって作成されたRAMLはAPIの開発に大きな役割を果たしてきた。2018年、MuleSoftはSalesforceによって買収され、RAML
ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
この記事は、技術書典 11 で頒布中の「Vivliostyle で本を作ろう vol. 5」から抜粋した記事です。ご興味ありましたら、Vivliostyle を使って組版された本誌もぜひお買い求めください！ また、この記事以外の内容もすべて Vivliostyle 公式サイトで無料公開中です。 技術書やドキュメントを執筆する際、あなたはどのような形式で文章を書きますか？ 最近ではもっぱら Markdown で書かれることが多いですが、この Markdown を拡張するポテンシャルを持つお気に入りの OSS プロジェクト「MDX」を紹介します。 MDX = Markdown + JSX MDX の名前の由来は Markdown + JSX なので、MDX を理解するためにはまず JSX について知る必要があります。 JSX とは JavaScript の拡張構文の一つで、元々 React の
OpenAI API ドキュメントの日本語訳をこちらでまとめます。文字量の多いドキュメントなので、セクションごとに記事を分割しています。 今回は「GET STARTED 」のセクションからLibraries 、Models、TutorialsそしてUsage policiesを抜粋した後編です。 基本 DeepLで翻訳して、気になるところだけ書き換えています(ほぼ気になるところがないのが、DeepLのすごいところ)。原文との突き合わせができるようにはじめに原文を入れてますので、間違いなど見つけられましたら、ぜひご指摘ください。ご指摘箇所は随時反映させていただきます。 原文のリンクが有効になってますので、それぞれ必要な場合は原文リンクの方を参照ください。 前回のおさらいはこちら Python library｜Python ライブラリWe provide a Python library, w
2020年後半版Vue.jsを使ってる人には必ず知っていてほしいドキュメントに書かれていないComposition APIのコードの書き方とVuex vs provide/inject - Qiita
2020年後半版Vue.jsを使ってる人には必ず知っていてほしいドキュメントに書かれていないComposition APIのコードの書き方とVuex vs provide/injectJavaScriptVue.jsフロントエンドVuexCompositionAPI まえがき 最近iCAREさんの所で Vue.js を一緒にやらせていただいているのですが、フロントの技術スタックがかなりモダンであり、開発体験が良く、ノウハウをどんどん公開して良いと言っていただけたので、その内容を共有するシリーズです. 今回の記事の内容はiCareさんのDev Meetupで話した内容になります. 最近公式のソースを追った所、 Composition API はapiの紹介はあれども、コードの書き方やその背景、Tips等は全然見当たりませんでした. また、すごく強力なapiである provide/inject
ドキュメントファイルの解析と変換に特化したオープンソースツール「docling」を試してみた | DevelopersIO
AWS事業本部コンサルティング部の石川です。最近、文書ファイルの解析と変換に特化した オープンソースツール「docling」 が注目を集めています。このツールは、最先端のAIモデルを活用して、ドキュメントの構造を理解し、様々な形式に変換することができます。今回、実際にdoclingを使用して日本語のドキュメントファイルからMarkdownファイルとJSONファイルへ変換を試してみます。 doclingとは doclingは、ドキュメントの変換と解析に特化したオープンソースのPythonパッケージです。最先端の人工知能モデルを活用し、レイアウト解析にDocLayNetモデル、表構造認識にTableFormerモデルを使用しています。一般的なハードウェアで効率的に動作し、少ないリソースで高性能を発揮します。JSONやMarkdown形式への変換が可能で、拡張性も高く、新機能やモデルの追加が容易
どうも、初めまして。 tokeと申します。 今回は自分の失敗談を話したい、と思います。 実装する前にドキュメントを読まないと、最後になってゴールに辿り着けない可能性がある そういう経験をしたのでご紹介します。 例えば、自社で集めた顧客のデータを活用し、Marketoにデータ連携したいとします。 marketoのAPIドキュメントを調べると、顧客の情報を登録する手段では以下の２パターンがあります。 POST /rest/v1/leads.jsonを使うパターン 以下のドキュメントにあるPOST /rest/v1/leads.jsonを使って、顧客のデータを送信し、連携する事ができます。 https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/leads [※Marketoで
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開 ソフトウェアの開発や運用において、さまざまなオープンソースが重要な役割を果たすようになってきており、現在ではオープンソースを抜きにソフトウェア開発や利用を行うことがほとんど困難な時代になってきました。 オープンソースと適切に関わり、活用や推進をしていくことは、ソフトウェアに関わる企業にとって（それ以外の企業にとっても）戦略的に取り組むべき事項になってきているといえます。 そうした中で「Open Source Program Office」（OSPO）と呼ばれる組織への注目が少しずつ高まっています。 一般的にOSPOとは、企業のオープンソース戦略の策定と実行といった大きなものから、社内でのオープンソースに関する啓蒙と推進、
私のチームで行っているドキュメント管理方法の紹介(GitHub Actions, S3, AsciiDoc) | DevelopersIO
ドキュメントツールのインストール(Windows) Macの場合の設定方法は、本項の後に記載 PowerShellの起動 各種ツールをインストールするため、PowerShellを管理者として実行 Windowsボタンを押下 powershell と入力 右クリックで管理者として実行 を選択します Chocolateyのインストール 本手順は前述で起動したPowerShellを利用 1.Chocolatey のサイトにアクセスし、インストールコマンドをクリップボードへコピー 2.前項でコピーしたコマンドをPowerShellにペーストして実行します Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServiceP
GMOペパボ株式会社は、「インターネットで可能性をつなげる、ひろげる」というミッションのもと、レンタルサーバーやドメインの取得、ホームページやネットショップの作成、ハンドメイド作品の売買やオリジナルグッズを在庫を持たずに販売できるサービスなど、多様な事業を、多様なブランドで展開しています。このマルチブランド戦略は、個性的なペパボのサービスを特徴づけるだけでなく、市場を確保しつづけるリスクヘッジとしても機能する一方で、サービスを超えてデザインを展開するのが難しいという側面もありました。 そこで、ペパボでは、各サービスが個別に考えていているようなデザインの原則やガイドライン、その実装としてのカラーパレットやコンポーネントライブラリなどのアセットのうち、重複しているものをすべてのサービスで使えるように一般化した、共通基盤デザインシステムを開発することにしました。ペパボでは、この共通基盤デザインシ
Documentation as Codeで継続的なドキュメント運用を実現する / July Tech Festa 2021 winter
July Tech Festa 2021 winter [D-5] https://techfesta.connpass.com/event/193966/
はじめに 「研究用のプログラムにもテストコードやドキュメント書いたほうがいいよね。」 「分かっちゃいるけど、そんな面倒なことやってられないよ。」 という研究者あるあるを解決すべく、僕が普段実践している開発スタイルを紹介します。 この開発スタイルのすごいところは： テストやドキュメントを一切書かない場合と比べて 追加の工数がほぼゼロ。 普通にコーディングしているだけで、いつのまにかテストコードとドキュメントまでできあがっている。 実装、コメント、テスト、ドキュメントが自然に同期するので、保守しやすい。 Pythonを例に紹介しますが、コメント内にテストを書けるツールと、コメントからドキュメントを生成できるツールをもつ言語ならばどれにでも応用できるはずです。 この開発スタイルに至った背景 ソフトウェア開発において、テストコードやドキュメントを整備することでプログラムの品質が向上することは広く知
VSCode拡張機能 Draw.io Integration導入方法 先人の方がまとめて下さってます。⇒ VSCodeでDraw.ioが使えるようになったらしい！ Draw.ioでsvg形式のファイルを作成する 拡張子を.drawio.svgまたは.dio.svgにしてファイル作成すると、Draw.ioに関連付けられ、svg形式のファイルを作画＆作成できます。 mdファイルにsvgを埋め込む mdファイルに以下のように作成した画像（.drawio.svg)を埋め込むことができます。 マークダウン構文またはimgタグで記述します。 mdファイルの編集画面からDraw.io画面を開ければ... マークダウン構文で記載した場合、画像ファイルを cmd + クリック で開くことはできますが... 残念ながら、テキストエディタが開いてsvgのソースが表示されます。 Draw.i
データベースドキュメント生成コマンド tbls 更新情報（Mermaid対応 / schema.json / tbls outの強化） - Copy/Cut/Paste/Hatena
久しぶりのtblsの新機能紹介エントリです。 ドキュメントのER図出力にMermaidを指定できるようになりました ER図の出力フォーマットにMermaidを指定できるようになりました。次のように er.format: セクションか --er-format オプションに mermaid を指定することで変更できます。 er: format: mermaid 開発裏話 GitHubがMermaid対応したことで「tblsもMermaid対応してほしい」という要望や提案は以前より多く受け取っていました。 しかし、個人的にあまりメリットを見出せずそのままPull Request待ちとなっていたのですが、今回エイッと作ってみました。 Mermaid対応をするにあたって1つとても面倒な仕様がありました。それはMermaidはER図の多重度（カーディナリティ）の指定が必須となっていることでした。 もと
Infrastructure as Codeにおける理想のドキュメント管理を目指して #infrastudy | DevelopersIO
インフラをコードで管理するInfrastructure as Codeだからこそ、必要なドキュメントについての考察とそれの管理方法についてLTした様子です。 「なんや、この視聴者数… 震えが来るぜ・・・」 先日開催されたInfra Study Meetup #2「VM時代の開発とCloud Native時代の開発」 - connpassにおいて、「IaCにおける理想のドキュメント管理を目指す」という内容でLTしてきましたので、その内容をお届けします。 当日は、イベント内容も登壇者も超絶豪華で、なんとリアルタイム視聴者数1000人超えということで、さすがに自分も緊張しました。まじで。 青山さんのメインテーマがKubernetesの話であり、前後それに関わるテーマが中心の中、Kubernetesもコンテナも1ミリもでてこない発表にしたのですが、IaCに関わる普遍的な考慮ポイントについて喋れたの
75億ドキュメント以上のデータを保持するMongoDBを、Amazon EC2からMongoDB Atlasへ約3ヶ月で移設した方法 | CyberAgent Developers Blog
75億ドキュメント以上のデータを保持するMongoDBを、Amazon EC2からMongoDB Atlasへ約3ヶ月で移設した方法 はじめに タップル SREの赤野、CAM SREの庭木です。 タップルは2021年3月頃にMongoDB on Amazon EC2(以下EC2 MongoDB)からMongoDB Atlas(以下Atlas)への移設を行いました。 今回はこの移設での取り組みについて紹介します。 Atlasへ移設することになった経緯・目的 タップルでは定期的にキャパシティプランニングを目的とした負荷試験を実施しており、今後のDAU増加のシミュレーションに対してシステムのキャパシティが確保できるかを定期的に確認しています。 タップルSREのキャパシティプランニングの取り組みについては、以前発表させていただいた資料があるのでこちらにも目を通していただけると幸いです。 2020年
はじめに ひょんなことから React 公式ドキュメント日本語版のメンテナをやらせていただいています smikitky です。 この記事は、React 公式ドキュメントの翻訳作業が GitHub ベースでどのように行われているのかを解説したものです。ドキュメントの翻訳には色々な方法がありますが、React の現アプローチは非常に上手く行っていると個人的に考えています。部分的には似たアプローチを説明している既存記事も探せばありますが、少し詳しめに書くことで事前の不安を取り除き、「思ったより簡単そうだから、自分もあのライブラリのドキュメント翻訳をやってオープンソースに貢献してみよう」と思えるようになることを目標にしています。 想定読者は Git、GitHub、Markdown（ないし類似の軽量マークアップ言語）、および基本的な HTML の仕組みがわかる開発者です。何らかの静的サイトジェネレー
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。さらに、ドキュメントの具体的な書き方と、フィードバックの収集について話します。前回はこちらから。 ドキュメントは「書き始める」ことが大事 岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？ 10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。 ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？ （スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き
こんにちは。LINE Growth Technology福岡開発室でサーバーサイドエンジニアをしている中村です。 この記事では担当していたプロジェクトで実施した、Swaggerを使ったAPIドキュメントの作成と、BE（バックエンド）とFE（フロントエンド）間の連携について紹介します。 プロジェクトの説明 はじめに、今回LINE Growth Technology福岡開発室（以下「GT」）がシステムの設計開発を担当した、LINE公式アカウント審査ツールのプロジェクトについて説明します。 LINE公式アカウント審査ツールとは、LINE公式アカウントで認証済アカウントが申請された際に、申請内容が適切であるか審査するシステムです。 このシステムは、LINE公式アカウントが利用されている各国に存在する審査パートというチーム（以下「審査チーム」）によって利用され、日本以外の国家も含め、一日あたり平均約
マネジメント業を通じて考えた、プロジェクト全体像の認識齟齬を防ぐ誤解されないドキュメント作成術 - ANDPAD Tech Blog
アンドパッドの土方です。 本ブログではEMインタビューで取り上げておりますが、記事投稿は初めてです。 エンジニアマネージャーとしてのイベント登壇や、プロジェクト推進における案件の取りまとめ業務が増えてきており、それに伴ってドキュメントを作成する機会も増えてきました。 自分の考えを整理するとともに、アンドパッドのエンジニアにはこんなこと考えている人もいるよ、的な意味で紹介したいと思います。 何かの参考になれば幸いです。 結論！ 次項からは文字ばっかりで語っているだけになりますので先に結論を書きます。 断面を作るための切り方を意識する 網羅性、単一性を守る 二軸で表現する この三項を守ることで、理解されやすく誤解を招かないドキュメントの完成に近づけると考えています。 ではここからだらだら語ります。 ドキュメントの目的は？ そもそもドキュメントはなんのために作るものでしょうか。 私は、「認識を合
はじめに COUNTERWORKSバックエンドエンジニアの伊藤です。 この記事ではAPIドキュメント分割の知見を紹介します。 弊社では OpenAPI を使用したスキーマ駆動開発を採用しています。 1ファイルで管理していたところ、25000行を超える行数となり管理コストが高くなっていました。 そこで分割作業を実施したのですが、どのような方針でどう対応したかを紹介します。 1ファイルで運用するデメリット そもそもどんなデメリットが発生していたのかを記載します。 全体の構造が把握しづらく、新規参画者への認知負荷が高い 行数が多すぎるため、RubyMine など IDE やエディタのパフォーマンスが落ちる 1ファイルの内部で複数の箇所を参照しているが、それぞれCommand fで該当部分を探す必要がある。そのため、見ているコードの箇所が頻繁に飛んで情報が追いづらい 実際にやったこと 方針 チーム
さまざまなテストレベルとロールで活躍されている方々がテストコードをリーダブルにする方法について語り、それぞれの違いや共通点について議論する、「リーダブルなテストコードについて考えよう」。ここで株式会社ソニックガーデンの伊藤氏が登壇。リーダブルなテストコードとは何か、リーダブルなテストコードを書くための具体的な意識を紹介します。 伊藤氏の自己紹介 伊藤淳一氏：リーダブルコードという発表です。いきなり余談から入りますが、今日仕事をしていたらテストコードに助けられました。 仕様変更がいつ入ったのかを調べなきゃいけなくなってコミットを追いかけていったら、過去の僕がすごくわかりやすいテストコードを書いていて、仕様Aを仕様Bに変えることがdiffを見れば一目瞭然というようなものを作っていました。リーダブルなテストコードを書いてて良かったと思った日がこの勉強会の開催日で、ナイスタイミングだと思いました。
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
VSCodeをドキュメント作成に活用――テキストエディタ、Markdownエディタの設定と拡張機能を解説
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
「Google ドキュメント」でMarkdown記法の一部が利用可能に ～今後も対応を拡充／「Google Workspace」だけでなく、個人の「Google アカウント」でも利用可能
ドキュメントとコードが乖離しないように DMM .com のエンジニアが教えるGoaを使ったAPIサーバーの作りかた
Notionでのドキュメント管理の何がつらいか - パルカワ2
RAGにおけるドキュメント検索精度向上について(概要編)
OpenAPIを使ってAPIドキュメントとモックサーバーを良い感じにした話
ドキュメントの限界 - orangeitems’s diary
SQLite を再実装する時に役にたつドキュメント - kawasin73のブログ
ドキュメントベースの型安全なモバイルアプリ行動ログ基盤の構築 - クックパッド開発者ブログ
緊急事態宣言、一夜明けた街の姿 昼までのドキュメント - 日本経済新聞
RESTful APIの設計、開発、ドキュメント管理を手助けする「RAML」とは
Markdown を拡張する MDX はドキュメント作成の新たな可能性？
OpenAI API ドキュメント 日本語訳｜#2 GET STARTED 後編｜ゑぐみかるちゃあ
実装する前にきちんとドキュメントを読んだ方が良い、という話 - Qiita
「Visual Studio Code」に日本語テキストの校正機能を追加する拡張機能「テキスト校正くん」／「Visual Studio Code」でドキュメントもブログも書いてしまう人に是非お勧め【レビュー】
ペパボのデザインシステムのドキュメントを公開します - Pepabo Tech Portal
忙しい研究者のためのテストコードとドキュメントの書き方 - Qiita
VSCode上のマークダウン とDraw.ioでドキュメントを作成する - Qiita
オープンソースドキュメント翻訳プラットフォームとしての GitHub (React 日本語ドキュメントの例)
ユーザーはドキュメントを「読みにくるけれど読んでいない」 “流し読み”しやすいドキュメント作成のポイント
Swaggerを使ったAPIドキュメントの作成と、バックエンドとフロントエンド間の連携
25000行超えのAPIドキュメントを分割した話
過度なDRYを行わず、APIドキュメントだと思って書く 脳内メモリを消費させない“リーダブルなテストコード”の書き方