情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
ドキュメントを書かないことは「負債を生む」ということ - Qiita
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
日本語表記ガイドラインのすすめ
こんにちは、技術開発チームの滝澤です。 わたしは弊社のブログや資料などの文書に対して技術的観点からの確認を依頼されることがあります。しかし、内容以前に日本語表記の点で気になり、指摘することが多いです。それでは、どのような点に注意して文章を作成すればよいでしょうか。日本語表記についてのガイドラインや参考資料がウェブ上で閲覧できるので、それを利用すればよいです。本記事ではそのガイドラインや参考資料について紹介します。 なお、本記事は社内勉強会で発表した資料に加筆して再構成したものです。 まとめ 結論を先に述べると、日本語表記ガイドラインとしては次の資料が参考になります。 公用文作成の考え方（建議） JTF日本語標準スタイルガイド（翻訳用） 外来語（カタカナ）表記ガイドライン第3版 書籍『日本語表記ルールブック第2版』日本エディタースクール編 書籍『日本語スタイルガイド（第3版）』一般財団法人テ
卒業論文や修士論文を書く学生へ｜Dr. Kano
毎年，１０名以上の学生の修士論文や卒業論文を添削する．これまで添削していて気になったことを，Twitterなどに書き散らかしたりしてきたが，まとめてメモしておく．（以下の文章は2015年2月に書いたものを編集したものです） 第１段階：正しく書く論文に限らず，文章を書くときには，正しい言葉で書くことを常に意識すべきだ．読みやすいとか，分かりやすいとか，それらも当然大切だが，それら以前に，正しくなければならない． 誤字脱字のある論文原稿やレポートを書く人には，「そういうケアレスミスのある論文やレポートに書いてあるデータや結果を信じろと言われても無理ですよね」といつも言っている． 正しく書けないとしたら，根本的な問題は日本語能力の低さだろう．言葉を正確に使えないのに，緻密に考えられるはずがないだろう．ウィトゲンシュタインの論理哲学論考でも読むか？ 第２段階：良い文章を書く正しい言葉で，論理的で読
卒業論文の書き方
やればできる 卒論の書き方 中田 亨 2003年10月15日初版。2009年4月27日改訂 工学部の標準的な卒論の書き方について説明します。修士論文でも博士論文でも書き方は同じです。 第１部 卒論クイックスタート 卒論とは？ 他人の真似ではないアイデアが、 それが理論的に可能である理由、 やってみた証拠、 どんなふうに役に立つか、 とともに記述されている、組織立った文書。 卒論は習作であり、基準は甘い。対外発表論文では第１条が「他人のアイデアより明らかに優れたアイデア」と厳しくなる。 「新しい意味を伝えることが、命題の本質である。」（ウィトゲンシュタイン） 標準的な卒論の構成 題目： 説明的なタイトルを付ける。例えば「人体計測装置の研究」では舌足らずであり、「赤外線平行投影法を用いた人体計測装置」とか、「海中でも使用可能な人体計測装置」などがよい。（私の上司の金出武雄氏の方式）。 要約：
卒論・修論の注意点
Tanichu/たにちゅー (Tadahiro Taniguchi, 谷口忠大） @tanichu （卒論・修論）先生や先輩の指摘を受けた後卒論を再提出するときには，どこを変更したかわかるようにしましょう．PDFなら蛍光ペン，texなら フォントの色を変えるなどして，わかるように．また，指摘点に対しては箇条書きで，それぞれどう反映したかの返事を書きましょう．先生感激します． 2013-02-02 12:13:14 Tanichu/たにちゅー (Tadahiro Taniguchi, 谷口忠大） @tanichu （卒論・修論） 提案手法の中で既存手法をいくつか利用している場合は，あまり章の中で既存手法の説明を書くと，なにが提案かぼやけるので，それらは 「えいや！」っと，付録・Appendix に回すのもありです． tex 的にはコピペで飛ばせて，スリムアップできます． 2013-02-02
修論(D論)参考 - NextReality
研究室内文書から転載します。前回のエントリ「よい論文の書き方」と多少重複してますが、修論（D論）執筆についての注意ポイントです。おもに工学系（コンピュータサイエンス系）論文を想定しています： まず「結局この修論では何を研究した（何を明らかにした、何を解決した）」を明確にしておく。１センテンスで書けるか。３項目ぐらいの箇条書きでまとめられるか。メインクレーム、イシューセンテンスなどと呼ばれる。(参考：クレーム(claim)とは)。論文を書く段階になってまだここがふらついている場合は、まずまともな論文にはならない。研究を着手する段階から常に意識しておくことが望ましい（「1センテンス、数項目で書ける」内容なので、研究の進捗に伴って変化することもありえる。が、考えなしに漫然と作業していて、さあ論文（修論・博論）まとめられるか、といってもそれは無理)。 誰に読んでもらう文書（論文）なのかを認識する。
よい論文の書き方 - NextReality
研究室用に書いた文書を転載します。主に工学系（コンピュータサイエンス系）分野の査読付き学会や論文誌に投稿することを想定しています。 以下は論文を書くときに個人的に気をつけていることです： メッセージをシンプルに：要するに何が言いたいのかが一言でサマライズできていること。記憶に残ること。 メッセージが伝わらないと、そもそも査読で落とされるし、たとえ学会で発表できたとしても誰も覚えていてくれない。実際、国際学会でも発表論文の多くが誰にもリファーされず、翌年になると忘れられている (どんな論文がどのくらい参照されているかはGoogle Scholar, Microsoft Academic Searchなどでわかる）。 問題はなにか・なぜこの問題が重要なのか・問題の原因は何か・どんな解決案を提案するのか・その効果は本当か・他にどんな研究があるか（なぜそれらの既存研究ではだめなのか）・誰のために役
How to write MS thesis.
修士論文作成の前半の工程において、既存の学会発表論文からのカット＆ペースト作業を生じることは否定しません。しかしその後に、例えば以下の観点からの書き加えが必要であることを、念頭に置いてください。 当該分野の専門家に限らず、幅広い読み手を想定して、くどいくらい丁寧な説明を心がける。特に研究の背景を紹介する章では、学会発表原稿よりも広い視野での説明を加える。 自分が目にした論文、教科書、ウェブなどを、あますことなく参考文献に加えて、関連研究の章などで紹介する。その分野において世界中で自分が最も多くの参考文献を知っている、というくらいの姿勢を示すべき。 提案手法の具体的な処理手順を説明する章では、修士論文の読者が同じ手法を再現できるのに十分なくらい、細かいところまで説明をする。 2年間でやったことのうち、あまり成功でなかった実行結果、ページ数制限のために学会発表原稿から省いた実行結果などを、でき
論文の読み方・書き方
金森 由博 (kanamori<AT>cs.tsukuba.ac.jp) 2023/8/9, ver. 1.3 2016/1/30, ver. 1.2 2014/6/13, ver. 1.1 2012/12/10, ver. 1 はじめに 論文は一定の型に従って書かれています。ここでいう「型」とは「どこにどんなことが書いてある」という論文の構造のことです。この構造に慣れれば、論文を読むときには読解しやすくなります。また自分が論文を書くときには、型通りに書くことで読者が安心して読める論文になります。書き方がわかれば自ずと読めるようになるはず、という考えのもと、ここでは書き方を中心に説明します。この文書では CG 分野を想定して論文の定型について紹介しますが、他の分野でも通用するはずです。 論文を書く上での細かい注意事項については、拙著「論文執筆のためのチェックリスト」を参照してください。 論
MkDocsを使って、簡単にドキュメント公開♪ - Qiita
この記事は BrainPad AdventCalendar 2023 14日目の記事です。 はじめに こんにちは。毎年この時期だけ活動して、なんとなくやっている雰囲気を出すのが得意な@yagizoです。 最近は開発系組織のいろいろなところに首を突っ込んで(いくつかの組織を兼務して)、エンジニアの組織運営を支援したり、エンジニアと他の部署のハブとして奔走したり、既存のプロダクトに新しい武器(機能)を授けるために企画・開発をしたり、新しいサービス企画検討をしたりと、忙しくも充実した日々を送っております。 さて、本題です。 みなさん、開発のドキュメント（APIや機能などプロダクト、サービスの仕様書、説明書）って、何を使って書いていますか？ 私の所属するチームでは、普段 Sphinxを使って、プロダクトのユーザーガイドなどのHTMLドキュメントを作成しているのですが、「Sphinxってなんでもでき
ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
AsciiDoc の画像をVSCodeでうまいこと扱う - Qiita
VSCode のAsciiDoc extensionには、クリップボード上の画像を保存し画像の参照記述を挿入する機能1があります。これを利用することで、画像が多い手順書などをスムーズに作成できます。 具体的には、 1. スクリーンショットを取る 2. 画像を保存する 3. AsciiDoc上に画像の参照記述を記載する という手順の2,3がショットカットキーひとつで済むようになります。 基本的な挙動 AsciiDocファイルを編集中にショートカットを実行すると、 クリップボード上に保存されている画像がファイルとして保存され、 カーソルの位置に image::0-5-2020-13-13-28-PM.png[] のように保存された画像を表示するための記述が挿入される ショートカットキー Macの場合、 Cmd + Alt + v Winの場合、 Ctr + Alt + v 画像のファイル名 d
AsciiDocの執筆環境を用意する - Qiita
PS C:\Users\akinasu> code --install-extension joaompinto.asciidoctor-vscode Installing extensions... Installing extension 'joaompinto.asciidoctor-vscode' v2.7.15... Extension 'joaompinto.asciidoctor-vscode' v2.7.15 was successfully installed. ３. Visual Studio Codeを再起動します。 使い方 １. 拡張子が.asciidocまたは.adocのファイルを作成し、Visual Studio Codeで開きます。 ※拡張子は.ad、.ascでも構いません。 ２. ファイルを開いたら、Ctrl + k, vを入力すると右側にPreviewが表
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
卒業論文・修士論文の書き方
GitHub - redpen-cc/redpen: RedPen is an open source proofreading tool to check if your technical documents meet the writing standard. RedPen supports various markup text formats (Markdown, Textile, AsciiDoc, Re:VIEW, reStructuredText and LaTeX).
AsciidoctorとGradleでつくる文書執筆環境
asciidoctor/lib/asciidoctor.rb at main · asciidoctor/asciidoctor