ドキュメント執筆にもGit、ビルド、テストで再利用性や整合性を実現する「Writerside」、JetBrainsがプレビューリリース
Kotlinなどの開発元として知られるJetBrainsは、テクニカルドキュメントのための一連のツールを統合したドキュメントオーサリングツール「Writerside」のプレビューリリースを発表しました。 ソフトウェア開発においては、テキストで記述されたソースコードをGitでバージョン管理し、ビルドによって複数のソースコードを1つのアプリケーションへとまとめ上げ、コンパイルし、テストをして本番環境へのデプロイによりアプリケーションを公開します。 そしてこのプロセス全体を、さまざまな機能を備えたツールチェンを用いて自動化することで、ソフトウェア開発の効率を高めています。 一方で、例えばアプリケーションのチュートリアル、SDKやAPIのリファレンスドキュメントなどのドキュメントの制作過程においては、複数のファイルをフォルダにまとめ、手作業で目次のページとリンクさせることや、ソースコードのサンプル
tblsを使って既存データベースからデータベース定義書をMarkdownで出力する方法｜ふじい
データベースの寿命はアプリケーションよりも長い というけれど、データベース定義書というものが無く、カラム名やコメントやソースコードから使われ方を類推して、それっぽいところに、それっぽいデータを入れるなんてことありますよね。 またリレーションを確認するためテーブル全体を俯瞰して眺めたいって時もありますよね。 そんな時に、役立つのが既存のデータベースからデータベース定義書を作成してくれるtblsです。 tblsとはMITライセンスで公開されているOSSです。 tbls is a CI-Friendly tool for document a database, written in Go. Go言語で作られたデータベースをドキュメント化するためのCIフレンドリーツールです。 そうCIフレンドリーツールなんです。 ここではドキュメント生成に重点を置いて説明しますが、README.mdを見ると、下
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開
GitHub、あなたの会社にオープンソース担当部門「Open Source Program Office」を立ち上げて機能させるためのドキュメント群をオープンソースで公開 ソフトウェアの開発や運用において、さまざまなオープンソースが重要な役割を果たすようになってきており、現在ではオープンソースを抜きにソフトウェア開発や利用を行うことがほとんど困難な時代になってきました。 オープンソースと適切に関わり、活用や推進をしていくことは、ソフトウェアに関わる企業にとって（それ以外の企業にとっても）戦略的に取り組むべき事項になってきているといえます。 そうした中で「Open Source Program Office」（OSPO）と呼ばれる組織への注目が少しずつ高まっています。 一般的にOSPOとは、企業のオープンソース戦略の策定と実行といった大きなものから、社内でのオープンソースに関する啓蒙と推進、
エンジニア組織に発信文化を浸透させるには｜shu223
IT企業で駆け出しマネージャーをやっています。優秀なエンジニアの採用は難しいという文脈にしろ、技術力のアピールや情報共有の文脈にしろ、「やっぱもっと発信やっていかないとね」というところに着地する会社や組織は多いのではないでしょうか。 ただ、Qiitaでいいねが1でもついてる人は上位15%、トータル100いいねもあればもう上位3%というデータがあるように、発信をする人はエンジニア界隈でも実は希少種です。 「Qiitaのあれこれをひたすら分析してランキング」より「うちの会社でも技術発信していくぞ！」とテックブログを立ち上げて「書いていこう！」と呼びかけてみたものの、全然続かなかった、というケースも結構あるのではないでしょうか。 まだまだ道半ばではありますが、マネジメントしているチームにて、発信の量が約10倍に増え、習慣として定着させることにある程度成功したので、どういうことをやったのか、あるい
個人からチームまで、Notion での情報・タスク管理一元化完全解説
2020/11/27 (金) の WP ZoomUP #53 にて弊社 KITERETZ inc. (キテレツ) での Notion の活用法についてお話させていただきました。以下はそのときの資料ですが、こちらの記事はその内容を記事化したうえで、資料には入れられなかった動画での操作解説や、時間的にセミナーで話せなかったことを書き加えたものです。 💡 Notion 採用のきっかけ Product Hunt などで話題になったタイミングで、個人的に Notion を触ってみましたが、「Evernote と何が違うんだろ？」と思ったぐらいで、イマイチ良さがわかりませんでした。 しかし、キテレツは2年ほど前からメンバーが増え、情報を一覧できるシステムを導入してほしいという提案がありました。僕も、プロジェクトごとのタスク・進捗管理に加え、全プロジェクトのタスクを横断的に確認する方法を模索していまし
Terraform ベストプラクティスを整理してみました。 | DevelopersIO
こんにちは。クラメソのスジェです。 ほとんどのサービスにはベストプラクティス（=best practices）というのがあります。 そのサービスを利用する際、このベストプラクティスを守るとより効率的に性能を100%活用することができます。 もちろんterraformにもこのようなベストプラクティスがあります。 今回はこのベストプラクティスについて整理してみました。 参考資料 本記事は下記の資料を参考にして作成しました。 本記事ではほとんどのプロジェクトに活用できる程度の項目を紹介しています。つまり、ベストプラクティスについて軽く説明している感じなので、詳細な内容までは上記の資料をご参照ください。 また、紹介した資料以外にもベストプラクティスを調べてみたら、たくさんの資料がありますので、そちらもあわせて確認することをお勧めします。 読む前に 実際にベストプラクティスをプロジェクトに適用しよう
LINEの社内には「テクニカルライティング」の専門チームがあります - LINE ENGINEERING
こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。今日は「テクニカルライター」というお仕事と、LINEにあるテクニカルライティングの専門チームについてお話しします。 テクニカルライターという職種があります テクニカルライターって何をしてるの？何を書くの？ ドキュメントはどうやって書いてるの？ どんなメンバーで仕事をしてるの？ ドキュメントを書く以外にこんなこともしているよ でもドキュメントを書くだけだと技術力が下がらない？ どんな人がテクニカルライターに向いてるの？ テクニカルライターという職種があります 私はもともとウェブ制作会社のインフラエンジニアでした。とある技術書を書いたことをきっかけに「テクニカルライターとして一緒に働きませんか？」と声をかけてもらい、LINEへ転職するに至ったのですが、実はお誘いをい
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
本当に実践的なデザインドキュメントの書き方 第1回：なぜ渡されたワイヤーフレームは分かりにくいのか？ | アドビUX道場 #UXDojo
本当に実践的なデザインドキュメントの書き方 第1回：なぜ渡されたワイヤーフレームは分かりにくいのか？ | アドビUX道場 #UXDojo 連載 本当に実践的なデザインドキュメントの書き方 いきなり渡されたワイヤーフレームをデザインするよう言われて戸惑った経験は、デザイナーなら誰でもあるのではないでしょうか？これはディレクターとデザイナーの分業という状況に起因する問題ですが、分業が一般的なのにはもちろん理由があります。そこで、この連載では、現在の分業体制を前提に、情報設計に関わる『デザインドキュメント』をきちんと制作することで、この問題を解決する手段を探ります。 第1回は、受託のWeb制作における一般的な分業体制を詳細に分析し、よりデザイナーが貢献できる役割分担について考えていきます。 なかなかはじめられないUXデザイン これはGoogleトレンドで、「Webディレクター」「Webデザイナー
HTTPキャッシュに学ぶ、無理のないドキュメント更新運用
LAPRAS株式会社でSREをしていますyktakaha4と申します 🐧 私は 2021 年の 1 月に LAPRAS に入社 したのですが、 入社以来ほそぼそとやってきた、ドキュメンテーションに関する取り組みについて一年ほど運用し一区切りがついたので、その話をしたいと思います✍ ことのおこり 現在弊社には正社員・業務委託あわせて 18 名程度のエンジニアが在籍 していますが、 私が入社した頃はエンジニアが7名程度、かつ全体の人数に対して在任歴の長い人が多かったこともあり、 開発者が参照するドキュメント管理について、比較的牧歌的な運用がなされていました 🐑 具体的には、開発環境の構築方法が古い手順のまま放置されていたり、オンボーディングに使うドキュメントが口伝されていたりと、 ドキュメント自体は存在するものの、それらが 古くなっていたり一覧化が不十分であることが検知できず、時間経過に伴
超上流から攻めるIT化の事例集：システム化の方向性と計画 | アーカイブ | IPA 独立行政法人 情報処理推進機構
・方向性と計画 成果物は「経営者が参画する要求品質の確保」に記述されている 表4．2「役割分担と成果物例」にならい分類・表示している。 要件定義についてはこちら
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
GitLabで学んだ最高の働き方。気持ちよく働くための組織と個人のテクニック（前編）。デブサミ2022
今日は「GitLabで学んだ最高の働き方」ということで発表していきたいと思います。 私、伊藤と佐々木はGitLabでソリューションアーキテクトをやっている者です。 GitLabは、オンプレミス用のソフトウェアと、GitLab.comも長年やっておりますのでぜひ使ってください。去年めでたく上場しましたので、さらにいろんな機能を追加して強力なDevOpsプラットフォームとして展開していきたいと思っています。 このセッションで共有したい内容の背景、これは個人的にGitLab社に参画した理由のひとつでもあるのですが、製品が魅力的であることともうひとつ、GitLabはご存じの通り、ご存じない方もいるかもしれませんが、従業員全員がリモートワークをしている企業です。 そこなら最先端のやり方での働きができるのではないか、という仮説が私の中にありまして、入社しました。 で、実際どうだったかというと、はい、最
GitHub Actions で簡単にバージョン番号付きリリースとリリースノートを作成する方法
対象読者判定フロー 以下の質問にはいかいいえで答えてください。 Q1: GitHub を使用していますか？ はいの方→次の質問に進んでください。 いいえの方→対象外です。すみません。 Q2: ソースコードなどの変更は全てプルリクエストで行って（＝master/main 直コミットはしていない（多少ならOK））いますか？ はいの方→次の質問に進んでください。 いいえの方→まずはプルリクエストベースの開発に切り替えてみてはいかがでしょう？ その後で続きを読んでください。 Q3: リリースノートをちゃんと書いていますか？ はいの方→基本的に対象外です。継続して書いていって下さい。楽をしたいと思ってる場合は続きを読んでください。 いいえの方→あなたは対象読者です！ この記事を読んで、お手軽自動生成でも良いのでリリースノートを作成しましょう！ はじめに 公開しているソフトウエアにバージョン番号を付け
エンジニアのための、いますぐ使える文章校正テクニック - ICS MEDIA
ウェブ制作や開発の仕事で文章を扱う機会は多いはず。書き手は不自然に思っていない文章でも、読み手は違和感をもっていることがあります。文章校正テクニックを覚えるだけでおかしな表現は少なくなり、読みやすい文章を書けるようになります。 本記事では、ICS MEDIAで実践している文章校正の一例を紹介します。 レベル1、基本的な校正ルールを使う いろんな場面で使える基本的な文章校正テクニックから紹介します。 テクノロジー系の名詞は正しく記載しているか テクノロジー系の名詞を間違って使うと、「本当に技術に詳しいの？」と読者からの信頼度が下がります。名詞は大文字小文字、スペース有無含めて正確に記述しましょう。 Github → GitHub（Hは大文字） Javascript → JavaScript（Sは大文字） After Effect → After Effects（複数形の「s」を忘れてはいけな
OpenAPI Specification ドリブンな開発事例とそれを支えるツール - NTT Communications Engineers' Blog
これは NTT Communications Advent Calendar 2021 3日目の記事です。 こんにちは、イノベーションセンターの松田 (@take4mats) です。 当社の Smart Data Platform (SDPF) のサービスラインナップの多くは、お客さまがサービスご利用に必要な操作を統一的に行うための Web UI に加え、同等の Web API を提供しています。 API 仕様は Knowledge Center にてサービスごとに一般公開されているのをご存知でしょうか？ (Knowledge Center で各サービス内の APIリファレンス のページをご覧ください。例えば こちらのリンク) この一般公開されている API 仕様はサービス開発初期に作成され、開発期間にも重要な役割を果たしています。 本記事では、その中で私が携わったサービスから、 API
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - k1LoW/tbls: tbls is a CI-Friendly tool for document a database, written in Go.
テクニカルライティングの基本
Mermaid | Diagramming and charting tool