3/30 に X で Terraform がトレンド入りしていて何事かと思ったら Terraform が公式ドキュメントとしてスタイルガイドを出したようです。 Terraform Style Guide いままで Terraform のスタイルに関して信頼できるドキュメントといえば Google Cloud の Terraform を使用するためのベスト プラクティス ぐらいしか知らなかったのですが、 Terraform 公式がようやく出してくれてありがたい限りです。 これでわざわざ社内の Terraform 規約を設けずとも「公式ドキュメントに従いましょう。」の一言で済みます。 ということで一通り読んだのでまとめました。 原文だと構文の簡単な使い方なども書いてありますが以下の要約ではだいたい省略しています。 詳細は原文を読んで確認してください。 要約 スタイルガイドについて コードのスタ

こんにちは ! テクニカルトレーナーの杉本圭太です ! 最近読んで面白かった漫画は「海が走るエンドロール」です。 私は業務でお客様に AWS の様々なトレーニングを提供しているのですが、コースによっては AWS を利用したシステムのアーキテクチャ図を受講者自身に描いていただく演習を取り入れており、よくこんな相談を受けます。 「どうやって AWS のアーキテクチャ図を描くのが正解なんですか ?」 AWS のアーキテクチャ図を描く状況は以下のように様々な場面であり、同じような疑問や悩みをお持ちの方も多いのではないでしょうか ? 詳細設計で構成図が必要 チームで wiki などに図を貼り付けて残したい 構成検討フェーズなどで図を見てディスカッションしたい ワークショップを試しながら理解を深めるなど自分のために描きたい そこで今回は AWS アーキテクチャ図をどうやって描けば良いか悩んでいる方へ、

自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検

Join our community of software engineering leaders and aspirational developers. Always stay in-the-know by getting the most important news and exclusive content delivered fresh to your inbox to learn more about at-scale software development.

概要 Design Documentと聞くと何を想像しますか？ 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの？」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは？ Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて

テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://spe…

エムスリーエンジニアリンググループ AI・機械学習チームでソフトウェアエンジニアをしている中村(po3rin) です。好きな言語はGo。情報検索系の話が好物です。今回は多様性を考慮したリランキング手法と実際にPythonで実装を試した話をします。 課題 検索結果のリランキング リランキング実装 アーキテクチャ 前準備 TF-IDF vector Jaccard係数 本実装の課題 まとめ We're hiring !!! Reference 課題 エムスリーのAskDoctorsというサービスではユーザーがお医者さんに直接質問ができるサービスです。質問できる以外にも、ユーザーは自分の症状や悩みに近い質問を検索できます。 www.askdoctors.jp Askdoctorsの検索の問題点として、同じようなタイトルが並んでしまうという問題があります。ユーザーの投稿ドキュメントのタイトルには「

開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。 ARCHITECTURE.md https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラ

この連載は、現在のWeb制作における分業体制を前提に、情報設計に関わる『デザインドキュメント』をきちんと制作することで、受託側と発注側のミゾを埋める手段を探ります。 前回は、デザインドキュメントの中でも、ユーザー（ペルソナ）の行動を時系列に並べて見える化できる「簡易カスタマージャーニーマップ（CJM）」をご紹介しました。今回はこの簡易CJMをもとに、理想の体験を考えるためのシナリオの解説と作成方法をご紹介します。 シナリオとは何か？ シナリオとは、ユーザーの行動を時系列に記述したものです。大別すると、現状を表したものと、理想的な状態を書き表したものに分けられます。ただ、UXデザインの文脈においては、ユーザーが理想的なかたちでゴールに向かっていくさまを書き記した「理想シナリオ」を指して、シナリオと呼ぶケースが多いように思います。この記事で説明するのは理想シナリオです。 現状理解としてのCJM

Understanding memory usage in Docker Desktop on Mac There have been many reports of possible memory leaks and apparent high memory usage of Docker Desktop since the upgrade to macOS 10.14 (Mojave). This document summarises the investigation into these reports and includes recommendations to help...

最新のmacOSに対応した仮想オーディオ入出力ユーティリティ「BlackHole」を利用してGoogleドキュメントに議事録などの自動文字起こしをしてもらう方法です。詳細は以下から。 以前、既に開発が終了したCycling ’74チームのSoundFlowerのように、特定のアプリからの音声を他のアプリに送るれる仮想オーディオデバイスをMac内に作成できる仮想オーディオ入出力ユーティリティ「BlackHole」を紹介したさい、WWDCのセッションや議事録をGoogleドキュメントの音声入力に接続することで簡単に文字起こしができるという事を教えていただいたので試してみてください。(コメントでのご指摘ありがとうございます) 設定 まず、文字起こしを行う音源が入ったMacにBlackHoleをインストールし、macOSのAudio MIDI設定アプリからBlackHoleの仮想オーディオデバイス

This post highlights some of the key components of good documentation, and goes through some of the steps you could take to improve the way you document your code. Documentation is one of the most important and under-rated aspects of any library or open-source project. If you are writing code that will be used by someone other than yourself, it needs to be documented. Period. After using many libr

前置き これはRustを学びたいけどどうやって勉強しようかという人向けの記事です。 自分の経験からここ先に読んどきゃよかったとか、ここ読んどけばもっと楽だったとかそんなのをいろいろまとめてあります。もう一度Rustを学び直すならどうするかなー、と考えながら書きました。なお大半が英語の資料です。 英語か・・・と思った方はyukiさんのRust を始めるための資料集もどうぞ。 対象はRuby、Pythonなどの高レベル言語をすでに習得してる人。 前準備 Rustの主な特徴を知っておきましょう。Rustは他の言語にない考え方や特徴が多いので先に知っておくと良いです。とりあえずinto_rust() : screencasts for learning Rustを全部見ましょう 基礎知識の習得 The Bookと呼ばれる公式の入門書があります。まずこれを読みましょう。日本語訳もありますが英語版のほ

github.blog GitHub Actions の新バージョンが 8/8 に発表されました。 www.kaizenprogrammer.com 自分は過去にも旧バージョン時に GitHub Actions の入門記事を書いていたのですが、新バージョンがこれまでと大きく変わってしまっているので、この記事ではあらためて GitHub Actions についていろいろ調べたり動かしてみたりした内容をまとめます。 目次 注意事項 GitHub Actions とは これまでの GitHub Actions とどこが変わったか コンセプト マルチプラットフォーム対応 HCL から YAML へ 料金 その他 GitHub Actions と Azure Pipelines 簡単な例 (Hello, World) ワークフローの設定 ワークフローとは ワークフローを実行するイベント ワークフロー

技術ブログは「書く」というより「記す」というのがシックリきている、ソラコム松下(max)です 2017年3月にテック・エバとして活動を開始し、通算400回以上講演の他、ブログでも情報発信しています。 年間で20本以上のブログを書いてくるうちに、だんだんと書き方がわかってきました。ですので、今回は 技術ブログの書き方ブログ を紹介します！ 技術ブログは「未来の自分へのドキュメント」 技術ブログは普通のブログとは異なります。 未来の自分へのドキュメント です。 「あー、これ既にやったことあるなー。なんだっけ？」とググった先が自分のブログであってほしい、そんな思いで書いてみてください。一番最初の利用者が自分、すなわちドッグフーディングしましょう。これはサービス開発でも、ブログでも共通して言えることです。 もし、手元に「メモ的なテキスト」があるならば、それはブログにできるかもしれません。 まずはタ

私は技術書典4・5と、個人でサークル参加をしてきたサークル主です。本の制作環境を迷いながら選択することが多かったので、技術書典6にサークル参加される方への備忘録も兼ねて、まとめてみました。 まずは技術同人誌を執筆するための制作環境ですが、私が観測した範囲内では、以下のいずれかでした。 Microsoft Word / Googleドキュメント Markdown LaTeX InDesign / CLIP STUDIO Re:VIEW単体 Re:VIEW + (InDesign / CSS組版)などの組み合わせ VivliostyleでCSS組版 それぞれ簡単ではありますが、所感をつらつらと綴ってみます。なお、眠くて概要を説明する気力がなかったため「◯◯とは？」的な内容は、それぞれのワードで検索して補っていただけると幸いです。 Microsoft Word / Googleドキュメント Wo

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに この半年くらいで初めて本格的にチーム開発を行い、今では日常的に GitHub の Pull Request を使っています。 チームの方々には、基本的なことから応用的な部分まで様々な観点からレビューをしてもらって、大いに勉強になりました。 ただ、時には「新人にとっては厳しいレビュー」をいただき、1 人で傷つきモチベーションを落とすこともありました。 もちろんそれは悪意のあるものではなくて、新人とレビュワーのスキルのギャップによって意図せず生み出されてしまうものです。 そのような不幸なレビューによって苦しむ新人が減ることを願って