2023年6月28日に開催された「Findy×freee」さんのコラボイベントに登壇した「新人エンジニアが入っているプロジェクトにおけるREADMEの書き方」の登壇スライドです エ…
これまで、python.jpではPythonの日本語ドキュメントを公開してきたが、この度、ドキュメントのホスティングを終了し、docs.python.org へのリダイレクトのみをおこなうようになった。 www.python.jp 実に喜ばしいことである。これまで、日本語ドキュメントは python.jp においてある私家版でしかなかったが、python.orgで公開されることで、一定の公式っぽさを得ることができる。 また、python.jpは私が一人でほそぼそと、さくらインターネットの一番安いVPSで管理運用してきた。しかし、これからはPython本家の運用チームできっちり運用していただけるのである。 別に難しいことをしていたわけではないが、python.jp運営のプレッシャーはちょっとしたものだった。ここ近年のPythonブームも、私がちょっとしくじってドキュメントを参照できなくなる、
普段仕事をしてるとき、いろいろなことに気を使いながら仕事をしてると思う。たとえばissueには、その背景、やりたいことや期待する効果、制限事項、認識している副作用やリスクの情報等などを書くような運用ルールを作っているチームは多いらしい。しかし、私たちのチームではそういうルールはない。それでうまくいくんだっけっていう話をよく質問されるので、考えてみた。 コードの品質をカバーするためのコメント私たちは、常にわかりやすいコードを書けるとは限らない。解説として、コメントが役立つ場面はある。 ちょっと待ってよ「よし、Why notを書こう！」と言って上手く書けるのは、そうとうに経験を積んだ人だ。そして、経験を積んだ人は大体問題ない。悪いコードほどコメントが必要だが、良いコメントが書けるくらいならコードはもっと良くなってる。鶏と卵じゃん。 コメントについて議論する暇があったら、コードについて議論したほ
記事中のURLや内容、特にRailsやRubyのバージョンについて古くなっていることに気づいた方はぜひ編集リクエストください。 この記事はOkinawa.rbのAdventCalendar 5日目の記事です。 YassLabの業務時間中にQiita:Teamに書き溜めたものを編集して公開します。 4日目は @siman さんの「今年作った gem の紹介 (2017)」でした。 明日は @fullkawa さんのFinOpsのはなしです。 背景 人数が増えたり参加プロジェクトが増えるにつれ以下のような変化がおきました。 同じソフトウェアのさまざまなバージョンを扱うようになった コードレビューをする人・される人が増えた 同じソフトウェアでもバージョンによってAPIや使い方が異なる場合があります。 また、人によっては参考にする情報源がバラバラになってしまい、ソフトウェアの開発者が提供しているド
Debianでは(多くのディストリビューション同様)、GCCのマニュアル等を含んだドキュメントをパッケージでインストールできます。先月リリースされたDebian 9 ("Stretch")でも、gcc-6-docという名前のパッケージになっています(通常はgcc-docが依存するパッケージとして自動的にインストールされるはずです)。 このgcc-6-docパッケージがnon-freeという分類になっていることは意外かもしれません。実際、GCCのドキュメントは(多くのGNUプロジェクトのドキュメント同様)GNU Free Documentation License (GFDL) v1.3でライセンスされています。このバージョンのGFDLは(ある一定の条件を満たせば)、Creative Commons Attribution-ShareAlike (CC-BY-SA) 3.0ライセンスと併用す
はじめまして！ 株式会社 Aiming の土井です！ エンジニアをやっております！ 今回の開発者ブログでは、情報共有ツールとしての UML の活用方法について、現場での取り組みをご紹介させていただければと思います！ 技術仕様書の“図” どうやって書いてますか？ 株式会社 Aiming では、プロジェクトの Wiki やバグトラッキングに Redmine をメインに使っています。みなさんも既にご存知だったり、実際にバリバリ活用されていることとおもいます。 また、企画仕様書、技術仕様書などは Redmine の Wiki やエクセルに代表されるオフィススイート等を活用して作成しますが… 図の表現を求められるような仕様書を作る時に、どうやって作成しようか悩んだことはありませんか？ 標準ペイントソフトで頑張って作成 オフィススイートに含まれる、ドローツールを使って図を作成、画像吐き出し というケー
経緯 私の務めている会社ではMicrosoftさんの製品が主に使われています. 私はMicrosoft Wordを使うとあまりの使いづらさに集中力が切れて仕事の能率が著しく低下するのですが,そんな私に上司はある日「要件定義書書いて.」という言葉を投げかけてきました.要件定義書？また作業が滞る日々が続くと思ったので先手を打って起きました. 曰く,「PDF形式でも宜しいですか？」と. 上司は怪訝な顔をしながらも承諾してくださいました.これで,私の無駄なことに全力になってしまう本能が遺憾なく発揮されるのでした. 成果物 Latexで仕様書を書いた.GitLabで成果物管理をした. GitLabとJenkinsを連動させて,Push後に自動的にBuildするシステムを作り上げた. 無駄にLatexのMakefileに詳しくなった. 手順 Ubuntu 12.04でLaTeX環境を構築する GitL
■ [event] 2013年のアドベントカレンダーまとめを始めました 11月になったので、Advent Calendarのまとめ作業を始めました。 去年のやつはちょっと長くなりすぎたので、今年は言語別・技術系・その他の3つに分けてみました。 Advent Calendar 2013まとめ[プログラミング言語別] - NAVER まとめ Advent Calendar 2013まとめ[技術系] - NAVER まとめ Advent Calendar 2013まとめ[非技術系] - NAVER まとめ 主にQiitaとAdventarをチェックしています。漏れがあったら@yharaまでお知らせください。 ■ [github] Githubの緑のバーを伸ばすには、登録したメールアドレスを使うことが必要 Githubのユーザトップ (https://github.com/yhara ) の緑のや
Rubyの世界には「RubyのことはRubyに聞け」という格言があります1。 この格言に従い、早速Arrayクラスがどんなメソッドを持っているかRubyに聞いてみます。irbを使います。 % irb irb> Array.instance_methods(false) => [:inspect, :to_s, :to_a, :to_ary, :frozen?, :==, :eql?, :hash, :[], :[]=, :at, :fetch, :first, :last, :concat, :<<, :push, :pop, :shift, :unshift, :insert, :each, :each_index, :reverse_each, :length, :size, :empty?, :find_index, :index, :rindex, :join, :reverse,
Rubyを書いている人ならきっと一度以上はお世話になっているRubyリファレンスマニュアル、通称「るりま」。 これが前まではsvnでリポジトリ管理+修正はredmineでチケットを切って依頼、みたいなすげーダルいフローでなんか見付けても依頼が面倒で面倒で面倒で諦めていたんだが、これがなんとgithubに！ やった！！！！！！ https://github.com/rurema https://github.com/rurema/doctree https://github.com/rurema/bitclust ということで一度pullreqを送ったんだけど、すこし注意が必要だったのでここにメモる。みんな真似してどんどんpullreq送ろう！ 手順 以下の通り。 doctree リポジトリをforkしてclone pullreq送るために自分のアカウントでforkして、それをcloneして
最近、スマホからRESTでアクセスしてデータ取ってくるシステムのサーバーサイドを作ることが多いのですが、API仕様書書いてくれと言われて面倒になったので、なんとかしたかった。 そこで、そもそもRESTの入力と出力の仕様って、controllerのspecを書いていればそこに書いてあって出力も取れるので、それを整形してmarkdownにすりゃ大体OKじゃないかと思ったので、controllerのspecを流すついでに自動生成するようなGemを作りました。 Rubyistでない人にソース読んでくれ、とは言えないし。 joker1007/ghost_writer · GitHub なんかGemっぽいキラキラネームにしようと思って、それっぽい名前を付けましたが、相変わらず中身はしょぼいです。特に出力周りがw 後、rpsec-railsに依存しているので、railsじゃないと使えない。 使い方は、こ
ドキュメントコメント、書いてますか？ githubで公開するライブラリなど、特に人に見せるようなコードには、きっちりコメントを入れておきたいものですね。 せっかくなら世界中の人に使ってもらいたいので、頑張って英語で書きたい。 でも、やっぱり英語には自信がなくて、何度も辞書や既存のドキュメントを見直してしまう…。 こんなムダな日々におさらばするため、代表的なドキュメントをいくつかピックアップして、頻出表現をまとめました。 もうこれで迷わない！ …いや迷うけど、それでも負担はグッと減るはず！ 参考ライブラリ Java – Java Platform SE 6 Closure Library – Closure Library API Documentation Foundation – Foundation Framework Reference UIKit – UIKit Framewor
■ [ruby][event] Rubyの次世代リファレンスマニュアルを構想する会をやりました 参加者のみなさまありがとうございました。 http://partake.in/events/eb5eeeff-8d60-406d-a4e5-ac3c479a4b88 以下は議論のメモです。(まだぜんぜん整理できてなくて混沌としていますが…) とりあえず1/31が「中間報告」なので、それまでに何か動いて見せられるようなものを作りたいと思います。ソースはgithubに置きます。 ゴール 1. 日英以外への翻訳をやりやすくしたい * 何から始めれば良いかわかること * 一時的に翻訳して終わりではなく、最新版に追従していくのを助ける手段があること * 成果物が便利な形で利用できること(web, cli等) 2. 日英版を「統一」したい * 現状は、リファレンスサイトに何か機能を追加する場合に (例えば、
るりまサーチという最近の検索技術を使ってRubyのリファレンスマニュアルを検索するWebアプリケーションがあります。表向きの存在理由は「手早く簡単にドキュメントを検索できるシステムを提供することで、Rubyユーザが楽しくプログラミングすることを妨げないようにする」ですが、実はもう一つ理由があります。それは、「Rubyのリファレンスマニュアルをよいものにしている人たちがいることに気づいてもらう」というものです。 ここを読んでいる人の中に、他の人が実装したプログラミング言語やライブラリのドキュメントを書いて、メンテナンスしている（アップデートに追従するなど）人がどれだけいるのかわかりませんが、この作業はとても大変で根気のいる作業です。しかも、その成果をなかなか実感してもらえません。Ruby本体に新しい機能（例えば、「バイト長」ではなく「文字長」を数える機能）が入ったら、プログラムが簡潔になるな
はてなグループの終了日を2020年1月31日(金)に決定しました 以下のエントリの通り、今年末を目処にはてなグループを終了予定である旨をお知らせしておりました。 2019年末を目処に、はてなグループの提供を終了する予定です - はてなグループ日記 このたび、正式に終了日を決定いたしましたので、以下の通りご確認ください。 終了日: 2020年1月31日(金) エクスポート希望申請期限:2020年1月31日(金) 終了日以降は、はてなグループの閲覧および投稿は行えません。日記のエクスポートが必要な方は以下の記事にしたがって手続きをしてください。 はてなグループに投稿された日記データのエクスポートについて - はてなグループ日記 ご利用のみなさまにはご迷惑をおかけいたしますが、どうぞよろしくお願いいたします。 2020-06-25 追記 はてなグループ日記のエクスポートデータは2020年2月28
教えてくんモードです。 Rubyで、gem installした後、ざっとドキュメントを見たいとき、どうするのが良いでしょうか？ （→解決しました「gem serverを動かして、表示されたURLをブラウザで見る」らしいです） たとえば、Rubyで「はてなブックマーク」を使って遊びたいなと思ったとしましょう。るびこちゃんは以下のような行動を取りました。 （hatenaという文字列を含むモジュールを探しましょ♪） C:\>gem search hatena *** LOCAL GEMS *** （あ、gemって、デフォルトではローカルを探すんですね…） （じゃあ、--remoteオプションをつけましょ♪） C:\>gem search hatena --remote *** REMOTE GEMS *** hatenaapiauth (0.1.0) hatenaapigraph (0.2.2)
はてなグループの終了日を2020年1月31日(金)に決定しました 以下のエントリの通り、今年末を目処にはてなグループを終了予定である旨をお知らせしておりました。 2019年末を目処に、はてなグループの提供を終了する予定です - はてなグループ日記 このたび、正式に終了日を決定いたしましたので、以下の通りご確認ください。 終了日: 2020年1月31日(金) エクスポート希望申請期限:2020年1月31日(金) 終了日以降は、はてなグループの閲覧および投稿は行えません。日記のエクスポートが必要な方は以下の記事にしたがって手続きをしてください。 はてなグループに投稿された日記データのエクスポートについて - はてなグループ日記 ご利用のみなさまにはご迷惑をおかけいたしますが、どうぞよろしくお願いいたします。 2020-06-25 追記 はてなグループ日記のエクスポートデータは2020年2月28
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く