技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
Read the Docs(Sphinx)でオープンソースのドキュメントをいい感じに書いてみる
B! 139 0 0 0 最近良くGitHubなんかで公開されてるオープンソースのドキュメントを見ようとすると こんな感じの似たようなフォーマットで書かれているものが多くなっています。 余りに多いので最初GitHubのサービスかな、とか思ったんですが、 これはまた別のRead the Docsという ドキュメント用ホスティングサービスによるものでした。 Read the Docs Read the Docsでドキュメントを公開してみる Sphinxのインストール レポジトリ側の準備 Read the Docsへの登録 ページを作成 Indexページ ページ内容の編集(Markdown to reStructuredText) タイトル ハイパーリンク 画像 リンク付き画像 インラインマークアップ コードブロック リスト テーブル Pythonのモジュール説明 その他reStructured
Issue and Pull Request templates
ProductIssue and Pull Request templatesIt's hard to solve a problem when important details are missing. Now project maintainers can add templates for Issues and Pull Requests to projects, helping contributors share the right details… It’s hard to solve a problem when important details are missing. Now project maintainers can add templates for Issues and Pull Requests to projects, helping contribut
Why Static Site Generators Are The Next Big Thing — Smashing Magazine
At StaticGen, our open-source directory of static website generators, we’ve kept track of more than a hundred generators for more than a year now, and we’ve seen both the volume and popularity of these projects take off incredibly on GitHub during that time, going from just 50 to more than 100 generators and a total of more than 100,000 stars for static website generator repositories. Influential
Big Sky :: markdown を何時でもチャラーっとプレビューしたい。
ちょっと書き物をする用事があって、markdown で書かなきゃいけなかったんですが 余計なインストールの手間が不要で 余計な設定は一切不要で 使い勝手は Linux や Windows 全て同じで 出来れば Markdown 保存したら自動更新されて GitHub Flavour Markdown でコードハイライトト GitHub Flavour Markdown でテーブル表記 こういうのが欲しくて、あるアプリケーションを見つけたんだけど外部の JavaScript を使ってる上にそのリソースURLが無くなり動かなくなってて困ったので作った。 今後もこういう事あるだろうし、自分用に作っておくべきだと思った。書き物をする予定だったのに気付いたら作ってたのでしょうがない。僕のせいではない。 mattn/mkup - GitHub README.md mkup Portable Markd
mermaid.jsが素晴らしいけどなかなか使ってる人見かけないので実例晒す(追記あり) - Qiita
mermaid.jsとは JavaScriptのチャート作成ライブラリです。他にも似たようなのは色々ありますが、これ一本でフローチャート、シーケンス、ガントに対応してるので、個人的にお気に入り。 http://knsv.github.io/mermaid/ サイトの各チャートのページ見ると書き方と何ができるかはわかるので、ご覧あれ。 僕の使い方 JSのライブラリを自分でインポートして何かすることはほとんど無くて(後述の理由からガントだけJSで使ってるけど)、基本的には以下の2つの方法で使ってる。 Haroopad フリーでクロスプラットフォーム(OS X, Win, Linux)なMarkdownエディタ。 v0.13からmermaid.jsがインテグされているので、何もしなくてもそのまま使える。 mermaid.jsのグラフの書き方は、コード表記で、言語をmermaidにしてあげるだけ。
モダンなWebプロジェクトにおけるベストプラクティス | POSTD
Oktavilla では、私たちは定期的に新規プロジェクトを立ち上げています。数年にわたって、私たちはこうしたプロジェクトを通してベストプラクティスを見つけ出してきました。そのおかげで、新規メンバーがスムーズにプロジェクトに参加できるようになり、エラーを減らすこともできました。こうしたベストプラクティスを、組織内部、クライアントを問わず大半のプロジェクトに活用しています。結果として、私たちは高品質のWebプロジェクトを実現しています。ここでお伝えするのは、そのプロセスの一部です。 このブログ記事では、技術面に関わるベストプラクティスに焦点を絞りたいと思います。例えばセットアップや、プロジェクトのツールやプロセスを選択する際に考慮すべきことなどについてお伝えします。各プラクティスの文末に、詳細な情報へのリンクをいくつか貼っています。 READMEファイル まずは、プロジェクトで最も重要なファ
Filydoc：技術メモを公開するための何か - clock-up-blog
Filydoc というものを作りました 公開場所 GitHub：https://github.com/kobake/filydoc デモサイト：Filydoc 実用(?)サイト：clock-up-memo 特徴 シンプルに Markdown ファイルを公開するためだけの Web フレームワーク フォルダ分けすると、それがそのままツリー構造として公開される アイテムの順番は名前順になるのでファイル名をうまく付けて運用 PHP 駆動なので、フツーのレンタルサーバで動く (しかし実は全文検索で grep 呼んでるので、ここは環境依存かも。さくらのレンタルサーバでは動いた) 使い方 Filydoc の zip か tgz を http://filydoc.net/ から入手、解凍。 data フォルダ内の .md ファイルを編集。書式は Markdown。 必要に応じてファイル増やしたりフォルダ増
KLab若手エンジニアの これなぁに？ : 2014年3月度ALMレポート(株式会社グラニ様との合同開催)
カテゴリ 2014年3月度ALMレポート(株式会社グラニ様との合同開催) お久しぶりです、okabe-mです。 KLabでは毎月ALMという社内勉強会を開催しています。 ALMとは ALMとはAll Layer Meetingの略で、職種・役職・発表内容を問わない勉強会・発表会です。 内容的に高度なものである必要はありませんが、発表者自身が工夫した箇所があることを求められます。 また、発表者にはプレゼン練習、聴衆には質問する能力を養う機会を提供する目的もあります。 開催は東京六本木の本社で行われますが、TV会議システム、インターネットを通じて国内外の拠点に配信を行っています。 3月度は株式会社グラニ様との合同で勉強会を開催しました。 弊社と株式会社グラニ様でそれぞれ発表を2人ずつ発表して頂きました。 さっそく、レポートに移りましょう。 Github:eで仕様書を書こう(KLab株式会社 加
Gitterが一般βになったので早速やってみたんだけど、ムッチャ感動するレベルだった - Life goes on
Gitterに感動した 金曜にメールチェックしてたら「Gitterが一般βになったから誰でも参加できるようになったよ」ってメールが届いてた。 確か以前は抽選かなんかだったんだけど、アイディアがちょっと面白いなーと思って参加できるようになったらメールでお知らせしてもらおうと登録してたんだけど。 Gitter - Chat, for GitHub 早速、試してみたんだけど…久々に感動するレベルのWebサービスでした。 そもそもこのサービス何なのか知らない人が大半だと思うんで、ちょっと説明するとこんな感じです。 GitHubのリポジトリやOrganization単位でチャットルームを作ることができる まあ、これだけなんですが。WebアプリとMacアプリがあってiPhoneとかのモバイル対応はまだらしい。とはいえ、Webアプリの方をMobile Safariなんかで見たらそこそこ見やすい感じではあ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - jxnblk/mdx-deck: ♠️ React MDX-based presentation decks
Go言語初学者がConfluenceをMarkdownで書くためのCLIツールを開発した話 - DMM inside
Writing on GitHub - GitHub Docs