# Short introduction on how to create good source doc? **URL:** \ **Category:** Ruby\ **Created:** [November 19, 2007, 2:46pm UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643 "2007-11-19T14:46:05Z")\ **Posts on this page:** 5\ **Page:** 1
**Author:** ![josh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/45deac/32.png) [@josh](https://www.ruby-forum.com/u/josh)\ **Post date:** [November 19, 2007, 2:46pm UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643/1 "2007-11-19T14:46:05Z")
Hi all I’d like to document my Ruby sources in a clean and standardized way. But I couldn’t find a short introduction on how to do that, e.g. what markup tags to use etc.? Anyone can post me a link or two? Thanks Josh ---
**Author:** ![josh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/45deac/32.png) [@josh](https://www.ruby-forum.com/u/josh)\ **Post date:** [November 19, 2007, 3:35pm UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643/2 "2007-11-19T15:35:45Z")
On Nov 19, 6:46 am, Joshua M. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > I’d like to document my Ruby sources in a clean and standardized way. > But I couldn’t find a short introduction on how to do that, e.g. what > markup tags to use etc.? Anyone can post me a link or two? I think I use RDoc markup well and consistently in this file: [http://phrogz.net/RubyLibs/Ouroboros.rb](http://phrogz.net/RubyLibs/Ouroboros.rb) which produces: [http://phrogz.net/RubyLibs/rdoc/files/Ouroboros\_rb.html](http://phrogz.net/RubyLibs/rdoc/files/Ouroboros_rb.html) [http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html](http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html) when run through RDoc. Basically, if you want to document your code in a standard way, find a file whose documentation you think is good and follow its conventions. Just view the source of the ruby file. (Not HTML.) ---
**Author:** ![josh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/45deac/32.png) [@josh](https://www.ruby-forum.com/u/josh)\ **Post date:** [November 19, 2007, 7:05pm UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643/3 "2007-11-19T19:05:26Z")
On Nov 19, 3:31 pm, Phrogz [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > [http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html](http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html) > when run through RDoc. > > Basically, if you want to document your code in a standard way, find a > file whose documentation you think is good and follow its conventions. > Just view the source of the ruby file. (Not HTML.) Just to add a little observation. When writing documentation it’s beneficial to have as much real life examples of class and methods usage as you can think of. It’s easer to learn by example. ---
**Author:** ![josh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/45deac/32.png) [@josh](https://www.ruby-forum.com/u/josh)\ **Post date:** [November 20, 2007, 4:05am UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643/4 "2007-11-20T04:05:49Z")
On Nov 19, 12:12 pm, Joshua M. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > Thanks for the hint. Because I’m creating Ruby on Rails codes I’d like > to adhere to its documenting conventions. Sadly I don’t know where its > sources are. I’m on OS X 10.4 and installed Rails using Ruby Gems… Slim2:~ phrogz$ ls -Flag /usr/local/lib/ruby/gems/1.8/gems/ | grep -E “active|rails” drwxr-xr-x 10 wheel 340 Oct 19 13:09 activerecord-1.15.5/ drwxr-xr-x 5 wheel 170 Oct 19 13:07 activesupport-1.4.4/ drwxr-xr-x 16 wheel 544 Nov 1 21:58 rails-1.2.5/ ---
**Author:** ![josh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/45deac/32.png) [@josh](https://www.ruby-forum.com/u/josh)\ **Post date:** [November 19, 2007, 8:12pm UTC](https://www.ruby-forum.com/t/short-introduction-on-how-to-create-good-source-doc/120643/5 "2007-11-19T20:12:42Z")
Dejan D. wrote: > On Nov 19, 3:31 pm, Phrogz [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > > > [http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html](http://phrogz.net/RubyLibs/rdoc/classes/Ouroboros.html) > > when run through RDoc. > > > > Basically, if you want to document your code in a standard way, find a > > file whose documentation you think is good and follow its conventions. > > Just view the source of the ruby file. (Not HTML.) > > Just to add a little observation. > When writing documentation it’s beneficial to have as much real life > examples of class and methods usage as you can think of. > It’s easer to learn by example. Thanks for the hint. Because I’m creating Ruby on Rails codes I’d like to adhere to its documenting conventions. Sadly I don’t know where its sources are. I’m on OS X 10.4 and installed Rails using Ruby Gems…