以下の文章は、Dariusz Jemielniak による Wikipedia as a Role-Playing Game, or Why Some Academics Do Not Like Wikipedia の日本語訳である。 原文は、Joseph Reagle、Jackie Koerner 編 Wikipedia @ 20 の第10章になる。 本翻訳文書については、Shiro Kawai さんに誤訳の指摘を頂きました。ありがとうございました。 ウィキペディアと大学人の時にぎこちない関係を理解するもっとも良いやり方は、それをゲームと考えることだ。 ウィキペディアの編集を始める道筋はたくさんあって、そのすべての道で恥をかくとは限らないのだけれども、私が辿ったコースはそういうものだった。私は月におよそ20万人ものポーランド人に利用されている人気の無料オンライン辞書を運営していた。ポーラ
読み手を理解してより良いドキュメントを書こう / Write better documents by understanding your audience
ドキュメントを書くときに、みなさんが気をつけていることは何でしょう？ 情報の正確さや文章表現など、さまざまなことに気をつけていると思います。これらに加え、ドキュメントを書く上では、「読み手の理解」が重要です。今回は、2023年3月に発行された『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の内容を元に、どのようにして読み手を理解するか、そしてその重要性を一緒に考えていきたいと思います。 古木 亮太朗 / LINE株式会社 Developer Contentチーム テクニカルライター この資料は以下イベントで発表した内容です。 https://line.connpass.com/event/279668/
Linux Kernel Teaching — The Linux Kernel documentation
Linux Kernel Teaching¶ This is a collection of lectures and labs Linux kernel topics. The lectures focus on theoretical and Linux kernel exploration. The labs focus on device drivers topics and they resemble "howto" style documentation. Each topic has two parts: a walk-through the topic which contains an overview, the main abstractions, simple examples and pointers to APIs a hands-on part which co
Zenn や GitHub の Markdown から利用できる Mermaid には「Git ブランチを表現する」機能があります。 その機能を利用してみたところよい感じだったので、記述方法やカスタマイズについてなどを記事にしてみます。 Git ブランチを表現するとは？ ドキュメントでブランチの説明などを読んでいると下記のような図(グラフ)を見かけるかと思います。 図 1-1 AA によるブランチのグラフ A---B---C---D develop \ E---F---G topicA \ H---I---J topicB Mermaid の Gitgraph Diagrams を利用することにより、このような感じで表示できるようになります。 図 1-2 Mermaid によるブランチのグラフ 基本的な使い方 Mermaid 用コードブロックの先頭で gitGraph を記述し、Git の
こんにちは。Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。LINE社内で大評判のテクニカルライティング講座をブログにまとめてみたシリーズも第3弾になりました。（第1弾、第2弾もぜひ読んでください！） 今回の記事では、以下のようにトピックが多く集まったときに「自分が書いたトピックを（その情報が不要な人に）読ませないためのコツ」を説明します。具体的には、順番に気を配ったり、情報の分類を気をつけたり、タイトルを工夫したり、という話をします。 全部読んでもらおうとしていませんか？ おそらくほとんどの人は、ほかの人の文章を読むときに、必要そうな文だけピックアップして読んだり、タイトルだけで内容を判断したつもりになったりすると思います。検索エンジンで検索したときに、表示された内容だけで、文章の内容を推測して読むか読まないか決めますよね。そう
D2 Tour | D2 Documentation
D2 is a diagram scripting language that turns text to diagrams. It stands for Declarative Diagramming. Declarative, as in, you describe what you want diagrammed, it generates the image. For example, download the CLI, create a file named input.d2, copy paste the following, run this command, and you get the image below. NETWORKUSERAPI SERVERLOGSCELL TOWERONLINE PORTALDATA PROCESSORSATELLITESTRANSMIT
JAWS DAYS 2024の発表資料です == 自身の持つ技術知識を、どのようにして一冊の本に変えることができるのでしょうか？ 本セッションでは、商業誌、技術同人誌、Amazon Kindle ダイレクト・パブリッシングを通じて出版した経験を生かし、技術書執筆の全過程を詳細に解説します。アイデアの見つけ方から、効果的な執筆方法、出版プロセスまで、具体的なテクニックをAWS本の執筆例を元に公開します。 このセッションを通じて、あなたの技術知識を価値ある技術書に変える第一歩を踏み出しましょう。
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
Writing documentation is enough to make you rip your hair out without worrying about the design. Let us help you keep a few strands. Syntax is a beautiful documentation template built with Tailwind CSS and Next.js, designed and built by the Tailwind CSS team. Powered by Markdoc, the new Markdown-based authoring framework from Stripe, it's now easier than ever to focus on writing great documentatio
The future of tbls and "Documentation as Code" / phpconfuk 2023
https://fortee.jp/phpconfukuoka-2023/proposal/df1faefa-056a-493a-87d3-45934e96ea8c
Layer0というJamstackプラットフォームを試してみた記事です。 Jamstackプラットフォームが何かは表現しにくいですが、Netlify、Vercel、Cloudflare PagesみたいなSPAなアプリケーションとかをホスティングしてくれるサービスです。 Cloudflare Pages・Vercel ・Netlify の違いや使い分けをまとめる Layer0はMoovweb XDNという名前のプロダクトでしたが、2021年4月にLayer0へリブランディングしています。 Moovweb is officially Layer0! 📝 XDN = Experience Delivery Network Layer0は、Netlify、Vercel、Cloudflare PagesのようにSPAアプリケーションをホスティングできるプラットフォームです。 他のプラットフォーム
Jupyter Notebookと Boto3で AWS環境定義書を作成してみる | DevelopersIO
Jupyter Notebook(以降 Notebook) は実行可能なプログラムコードや分析結果、グラフなどを含んだドキュメントを作成するための OSSです。 画像：https://jupyter.org/ Pythonによるデータ分析でよく利用されます。 特徴として 「Markdown セル」と「Code セル」 を Notebook内へ配置できます。 データ分析のプロセスの文脈を Markdownセルに書くことで、 プログラムのコメント以上の表現力で、プロセスを記述できることできます。 データの可視化についても、Notebookは優秀です。 Matplotlib のグラフや、Pandas のテーブルなどを Notebook内にインライン表示してくれます。 さて、Markdownセルによるドキュメンテーション、 pandas によるテーブル表記でふと思いました。 「Jupyter No
[TypeScript]モノレポ管理ツール比較検討
モノレポ管理のツールを検討したときのメモ Background 自分が所属するチームで開発する JavaScript/TypeScript のプロダクトが増えてきて、同じような内容のリポジトリがいくつも存在している（n個とする）。 変更を加えていくにつれて、それぞれの差分が大きくなり、以下のような問題が発生する。 開発が止まっているプロジェクトの構成が古くなり、修正コストが発生する 開発が複数同時進行している場合、同じような実装を手動で同期する必要がある これらは共通の基盤等があれば効率的に（理想的にはn分の1の労力で）開発が可能であり、将来的なコストを考えると、いまのうちにその仕組みを考えておきたい。 Proposed Solutions 要件は以下 複数のパッケージをnpmとしてpublishできる アプリケーションも管理できる Nx, Rush, Lerna を主要な選択肢としている
![[TypeScript]モノレポ管理ツール比較検討](https://cdn-ak-scissors.b.st-hatena.com/image/square/e204665caf2bdc344987086461dd0424f7c8112d/height=288;version=1;width=512/https%3A%2F%2Fres.cloudinary.com%2Fzenn%2Fimage%2Fupload%2Fs--mp4vbqB0--%2Fc_fit%252Cg_north_west%252Cl_text%3Anotosansjp-medium.otf_55%3A%25255BTypeScript%25255D%2525E3%252583%2525A2%2525E3%252583%25258E%2525E3%252583%2525AC%2525E3%252583%25259D%2525E7%2525AE%2525A1%2525E7%252590%252586%2525E3%252583%252584%2525E3%252583%2525BC%2525E3%252583%2525AB%2525E6%2525AF%252594%2525E8%2525BC%252583%2525E6%2525A4%25259C%2525E8%2525A8%25258E%252Cw_1010%252Cx_90%252Cy_100%2Fg_south_west%252Cl_text%3Anotosansjp-medium.otf_37%3Aokmttdhr%252Cx_203%252Cy_121%2Fg_south_west%252Ch_90%252Cl_fetch%3AaHR0cHM6Ly9zdG9yYWdlLmdvb2dsZWFwaXMuY29tL3plbm4tdXNlci11cGxvYWQvYXZhdGFyL2I5NmZlMjc4YTYuanBlZw%3D%3D%252Cr_max%252Cw_90%252Cx_87%252Cy_95%2Fv1627283836%2Fdefault%2Fog-base-w1200-v2.png)
PHPカンファレンス小田原2024の登壇資料です。 https://fortee.jp/phpconodawara-2024/proposal/56218b4f-b724-4199-82f1-67497501a9ef ADRとはなにか？ なぜ、導入する必要があるのか？ 実際に導入してみて苦労したこと 良かったこと、悪かったこと
How to Write Good Documentation (And Its Essential Elements)
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
March 23, 2020 Please don't write your documentation in Markdown Please don't write your documentation in Markdown. Please. I'm begging you. Markdown is tolerable for short documentation, like a readme.md. Past that, it's the wrong tool for the job. Markdown is about formatting, not information Markdown is just a way to write simpler, nice looking HTML. There is direct mapping between _foo_ and <e
タイトルがすべてなのですが意外と知られていないのでご紹介します。 Google Documentをメモとして使う時は、メニューの「ファイル」→「ページ設定」から「ページ分けなし」を選択すると便利です。 Google Deocumentをメモに使ってる人は多いんじゃないかと思います。Chromeだけで使えるし、複数人での編集もできるし、ミーティングの議事録作成なんかにすごくいいツールですよね。 議事録のような「印刷を前提にしない用途」であれば、メニューの「ファイル」→「ページ設定」で「ページ分けなし」を選択してみましょう。 デフォルト設定デフォルトでは「ページ分けあり」かつ表示モードが「印刷レイアウトを表示」になっているため、ページの区切りと余白が表示されています。 「印刷レイアウトを表示」しないこのチェック「表示」メニューからオフにすると、ページ区切りの余白が消え、連続したドキュメントとし
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
日本語表記ガイドラインのすすめ
こんにちは、技術開発チームの滝澤です。 わたしは弊社のブログや資料などの文書に対して技術的観点からの確認を依頼されることがあります。しかし、内容以前に日本語表記の点で気になり、指摘することが多いです。それでは、どのような点に注意して文章を作成すればよいでしょうか。日本語表記についてのガイドラインや参考資料がウェブ上で閲覧できるので、それを利用すればよいです。本記事ではそのガイドラインや参考資料について紹介します。 なお、本記事は社内勉強会で発表した資料に加筆して再構成したものです。 まとめ 結論を先に述べると、日本語表記ガイドラインとしては次の資料が参考になります。 公用文作成の考え方（建議） JTF日本語標準スタイルガイド（翻訳用） 外来語（カタカナ）表記ガイドライン第3版 書籍『日本語表記ルールブック第2版』日本エディタースクール編 書籍『日本語スタイルガイド（第3版）』一般財団法人テ
技術記事の3類型: 初心者による技術記事執筆のすすめ
学習ノートが全て×となっていますが、これはそもそも学習ノートは読み手に価値を与えるものではないと定義しているので当たり前のことです。×と書くと学習ノートが悪いものであるような印象を受けるかもしれませんが、そのような主張をしているわけではないのでご安心ください。 ただし、初心者同士が「ノートを見せ合う」かのように、他の初心者の学習ノートを参考にできる場合もあるかもしれません。この場合はそれが「学習ノートである」と認識していることが前提です。学習ノートとして書かれたものを教科書だと思って参考にすると痛い目に遭うでしょう。 教科書は知識を提供するものなので、初心者や中級者に対して有効です。上級者の場合、知識はすでに知っているので教科書から新たに得られる価値はあまり多くないでしょう。ただし、上級者が教科書類型の記事をSNSでシェアしている様子は結構見られます。これは、その記事を利用してその上級者自
Swimlanes.io
Create sequence diagrams with simple online tool Swimlanes.io is a free webapp for making sequence diagrams. You simply edit the text on the left and the diagram is updated in real time. You can download your sequence diagrams as images or distribute with a link. title: Welcome to swimlanes.io One -> Two: Message note: **swimlanes.io** is a simple online tool for creating _sequence diagrams_. Edit
デザインシステムの目的を考える｜seya
デザインシステムの目的とは？ と問われるとあなたはどんな風に答えるでしょうか？ おそらく「ユーザに一貫性のある体験を提供するため」「デザイン資産を再利用できるようにして生産性を上げるため」そんな答えが一般的だと思います。私もそんな感じで捉えていましたし、間違いなくそれらはデザインシステムの効能だと思います。 が、細かいところをよくよく考えると「一貫性とは具体的にどこが一貫していることを指すのか」「一貫性を優先させることによってユーザの不利益になるシーンもあるがそれは本末転倒な結果なのではないのか」「生産性というのは "ユーザ体験の向上" を念頭に置いた場合であって、それが必要ないならシステム化しないで開発した方が速いのではないか」 そんな数々の疑問が私の頭に湧き上がり夜も8時間しか眠れなくなりました。 猫と寝る人間という訳でデザインシステムの目的をなるべく具体的に検討した軌跡を記したのがこ
textlint editor - ブラウザでも動くPrivacy Firstの文章校正ツールを作る話 自己紹介 Name : azu Twitter : @azu_re Website: Web scratch, JSer.info テーマ textlint Privacy Firstな校正ツールを作る サーバにデータを送らずに、ローカルで文章のチェックをする textlintとは? textlint textlintJavaScriptで書かれた文章のLintツール ESLintの文章版 Markdown、Re:View、HTMLなど文章構造をパースしてからチェックする 一般的なスペルチェッカーは構造を見ないので誤検知する 200弱ぐらいのルールがある Collection of textlint rule · textlint/textlint Wiki 日本語、英語、言語に依存しな
こんにちは、スープです。 ユビーでソフトウェアエンジニアをしています。 最近は、マイクロサービス化推進や社内のスクラムマスター育成のお仕事をしています。 この記事では、ユビーが長期的に設計と向き合うために採用しているプラクティスを紹介します。 Web スタートアップが陥りやすい技術の問題 一般的に、Web スタートアップでは価値検証のためのフィードバックサイクルを高速化することが重要視されます。それは極めて正しいことと思いますが、その反面、ソフトウェア設計が軽視されやすくもあります。単に「動くもの」を作ることが優先されるがあまり、ビジネス要件の変化に設計が耐えられなくなったり、チームの生産性が大きく下がったりするのを何度も見てきました。 また、Web スタートアップは人員の入れ替わりが激しいため、チームの誰にも既存のコードベースの設計意図やコンテキストがわからないということがよくあります。
TerraformInfrastructure as code provisioning
本コーナーでは技術へのタッチポイントを増やすことを目標に、各分野で活躍されている方をお迎えします。 今回はテクニカルライティングをテーマに堀越さんにインタビューします。書く技術の一端に触れて仕事や趣味に活かしてみませんか。 【話し手】 堀越 良子（HORIKOSHI Yoshiko）LINE ではたらくテクニカルライター。技術書典で『DNS をはじめよう』などのインフラ入門書を執筆。ねこが好き。 Twitter @mochikoAsTech GitHub mochikoAsTech URL https://mochikoastech.booth.pm/ 書く仕事 日高： 今のドキュメントを書くお仕事とは、どのように出会ったのでしょうか。 堀越： 私のキャリアはPHPエンジニアから始まっています。そのあと広報をやって、今の仕事の前はインフラエンジニアを7年ほどしていました。当時、仕事をしなが
日刊SPA！に登場の医学生投資家、儲け自慢に熱を入れるあまり「11歳から親の口座で投資を始めた」と借名取引をうっかり告白
Learn the basics of Xcode, SwiftUI, and UIKit to create compelling iOS apps.
OpenAPI + Redoc, Docusaurus, Mermaidで始めるスキーマ・ドキュメント駆動開発
OpenAPI + Redoc, Docusaurus, Mermaidで始めるスキーマ・ドキュメント駆動開発 【この本について】 この本はOpenAPIを使ってドキュメントを作成する方法を学びます。 OpenAPIを使ってドキュメントを作成することで継続的な開発を行うことができ、 OpenAPI Generatorを使ってドキュメントと実装のズレをなくすことができます。 また、Docusaurusを使ってドキュメントを作成することで、 運用ドキュメントを簡単に公開することができます。 本書では以下の内容を取り扱っています。 - Docusarusでドキュメント環境を構築する - OpenAPI + Redocでドキュメントを作成する - OpenAPI Generatorで自動生成する - Prismでモックサーバーを導入する OpenAPIを使ってみたい人、社内の設計・運用ドキュメント
インフラをコード化してVCSで管理するIaC。インフラの全てがコードで完結できることのメリットは無数にありますが、IaCだからこそ管理するべきドキュメントがあります。その管理方法についての視座をみなさんにお伝えできれば。
About | Divio Documentation
The Documentation System The Grand Unified Theory of Documentation – David Laing There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to
Jupyter Book is an open source project for building beautiful, publication-quality books, websites, and documents from source material that contains computational content. With this post, we’re happy to announce that Jupyter Book has been re-written from the ground up, making it easier to install, faster to use, and able to create more complex publishing content in your books. It is now supported
こんにちは、今年1年でキーボードを3回買い替えたUXライターのkunyです。今は、NiZのATOM 66を使っています。 SmartHRでは、textlintに独自のルールプリセットを追加して利用しています。textlintは4人で運用していますが、自分もメンバーの1人です。この記事では、textlintの便利さを世の中に伝えたく、textlintの利用シーンや利用者の生の声をご紹介します。 ※この記事は、2021年SmartHRアドベントカレンダーの13日目の記事です。 textlintの利用シーン 開発現場において、各自のローカル環境・GitHubと連携したCircleCIで文言の正誤を判定しています。 ローカル環境では、エディター上でコマンドを実行すると、「エラー内容」と「正しい表現」がわかります。コマンドで「正しい表現」に置き換えることもできますが、前後の文脈を確認しながら文言を修
AI infrastructure for customer supportAutomate customer support, scale without increasing headcount, and deliver exceptional user experiences. A suite of tools to scale your mighty customer support teamHandle more support volume by giving your team AI superpowers instead of increasing headcount. Markprompt fits in at all touch points in the agent and customer journey.
これだけ気を付けて書いてもらえるとみんな幸せになるポイント2つだけ / Two things to keep in mind about writing to make everyone happy
文章を書く技法的なものは多くあり、そういったものすべてに対応しなくても「わかりやすい文章だ！」と言っていいはずです。今回は、私が特に重要だと考えている「名前を大事にしてほしい話」と「あらかじめ読者との距離を近づけて欲しい話」の2つのポイントに絞って、文章を書くときのポイントをお伝えします。技術者の業務の一環として文章を書いている方、自分が書いている文章を改善したいけど、どこから手を付けると効率がいいか迷っている方に、きっかけを伝えるためのセッションです。 ■ 発表者 矢崎 誠 / LINE株式会社 テクニカルライター https://twitter.com/yazakimakoto ■ セッション動画 https://youtu.be/nmFVXJGiCxM?t=1017 ※こちらは以下イベント内で発表した内容です https://line.connpass.com/event/20565
議事録は、書く側にも読む側にも「なんか面倒くさいな」と思われがちです。しかし、議事録をないがしろにするのは、情報流通を疎かにすることと同じ。 議事録の質を高めることは、仕事の評価を高めるだけでなく、ビジネスを加速させる力となります。 このnoteでは、「残念な議事録を少なくする」をテーマに、「文章を書くのが苦手」「情報の論理構造の整理が苦手」という方にも、実践可能な方法を書いていこうと思います。 新人の仕事といえば…議事録今回、アドビさんの「みんなの資料作成」という企画に参加し、「新社会人向けに社内資料のノウハウ」をお伝えすることになりました。 Adobe Acrobat「みんなの資料作成」 新人が任せられる資料の代表例といえば…議事録ではないでしょうか。 多くの会議に必須な議事録ですが、面倒な仕事でもあります。現場では、新人メンバーが議事録をまかせられる傾向があります。 ただ、新社会人の
GitHub - k1LoW/ndiag: ndiag is a high-level architecture diagramming/documentation tool.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert
# はじめに GitHub Changelog を元に、GitHub Actions がどのように更新されていったかを簡単にまとめました。 あまり深いところまでは書いてないので、気になった変更があったら各自調べてください（もっと色々書きたかったけど時間なかった）。 わりと雑に作ったので漏れや間違いがあったらコメントとか下さい。 2021/12/01 までの情報をもとにこの記事は書かれています。 この記事は GitHub Actions Advent Calendar 2021 の 1 日目の記事です 🎅🎂 目次 # はじめに # 歴史 ## 発表 〜 正式リリース（2018/10 〜 2019/11） ## 2020 ### 1Q + α ### 2Q ### 3Q ### 4Q ## 2021 ### 1Q ### 2Q ### 3Q ### 4Q ## 2022 ### 1Q #
記事を書くときの自分ルール
この記事は アウトプットはいいぞカレンダー 2022 の 15 日の記事です。 はじめに 記事を書くのは結構好きで、Qiita や Zenn にごそごそと書き続けてたら計 100 記事をとっくに超えてました。今知りました。 「はえ〜そんなにあったのか」って気持ちです。 ちなみに 7 年ほど前の初投稿は、「こういうときはこうすると楽だぞ」ってドヤ顔でコード書いたやつで、数行しか書いてないくせにバグってました。 公開後に即コメント通知が来て、恐る恐る見たら何人かバグ指摘をしてくれてました、懐かしい。 「いんたーねっとこわい、けどやさしい」って思った思い出の記事です。 それから時は経ちある程度は書き慣れて、ここ数年はそれなりに一貫した自分ルールみたいなものができてきています。 気にすることが定まっていると書くとき楽なので、ちょっと整理して晒してみたいと思います。 ネタにしつつあわよくば自分ルール
【PDF】公用文作成の考え方（建議）
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ロールプレイングゲームとしてのウィキペディア、もしくは一部の大学人がウィキペディアを好きではない理由
Git ブランチの表現も Mermaid がよい感じに表示してくれました
LINE社内テクニカルライティング講座第3弾！不要な人に社内文書を読ませないコツ
技術書を書く技術 JAWS DAYS 2024
GitHub - docuowl/docuowl: 🦉 A documentation generator
Syntax - Tailwind CSS Documentation Template
JamstackプラットフォームのLayer0へNext.jsのアプリをデプロイしながら試す
ADRを一年運用してみた/adr_after_a_year
Please don't write your documentation in Markdown
Google Documentを「ページ分けなし」にするとメモに便利
GitHub - azu/github-sponsors-tax: GitHub Sponsorsの確定申告手順
textlint editor - ブラウザでも動くPrivacy Firstの文章校正ツールを作る話
ユビーが長期に渡ってソフトウェアを進化させ続けるためのドキュメンテーションプラクティス
CDK for Terraform Is Now Generally Available
第7回 技術を伝えるドキュメンテーション術 | gihyo.jp
クックパッドの決算補足説明資料、なぜか補足説明を放棄してポエムに注力 : 市況かぶ全力２階建
Develop apps for iOS | Apple Developer Documentation
IaCにおける理想のドキュメント管理を目指す
Announcing the new Jupyter Book
textlintプロジェクトの現在地 - SmartHR Tech Blog
Markprompt | AI for customer support
プロの議事録はここが違う。一目置かれる議事録作りの8つのメソッド｜長谷川 翔一 / 編集とマーケティング
GitHub Actionsの歴史（2021/12/1 更新） - cangoxina