# Documentation conventions **URL:** \ **Category:** Ruby\ **Created:** [February 8, 2010, 8:00pm UTC](https://www.ruby-forum.com/t/documentation-conventions/183130 "2010-02-08T20:00:58Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![quintus](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/q/49beb7/32.png) [@quintus](https://www.ruby-forum.com/u/quintus)\ **Post date:** [February 8, 2010, 8:00pm UTC](https://www.ruby-forum.com/t/documentation-conventions/183130/1 "2010-02-08T20:00:58Z")
Hi there, I’ve been searching the web for some time now, but I can’t find any reasonable conventions on how to write Ruby documentations. There are some pages out there describing what’s the best way to write Ruby source code, but if they cover documentation, they do it in just a very raw way, not going into depth. Instead, I’ve found other Ruby documentation tools, such as NaturalDocs and YARDOC, but I’m not convinced by any of them, because NaturalDocs doesn’t has any avantages over the usual RDoc (I think) and YARDOC seems to have problems with non-ASCII characters and is therefore useless if I want to or have to document my code in another language than English. So far, I’ve been happy with the markup RDoc provides (besides the fact that it doesn’t support nested lists ☹ ). Also, I want my documentation to be readable if someone _does not_ have a specific documentation tool beside RDoc installed. But there is this simple question: What are the documentation conventions that are used by wide parts of the Ruby community (_NOT_ the Rails community)? Can anybody point me somewhere? If not, I’d be happy to work out some “reference document”, or however to call that, which states which way documenting should go. Thoughts? Marvin ---
**Author:** ![quintus](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/q/49beb7/32.png) [@quintus](https://www.ruby-forum.com/u/quintus)\ **Post date:** [February 8, 2010, 8:02pm UTC](https://www.ruby-forum.com/t/documentation-conventions/183130/2 "2010-02-08T20:02:47Z")
Marvin Gülker wrote: > Hi there, > I’ve been searching the web for some time now, but I can’t find any > reasonable conventions on how to write Ruby documentations. There are > some pages out there describing what’s the best way to write Ruby source > code, but if they cover documentation, they do it in just a very raw > way, not going into depth. Look at the libraries you’re using. You’ll see that virtually everybody uses RDoc. Problem solved. Best, – Marnen Laibow-Koser [http://www.marnen.org](http://www.marnen.org) removed\_email\_address@domain.invalid ---
**Author:** ![quintus](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/q/49beb7/32.png) [@quintus](https://www.ruby-forum.com/u/quintus)\ **Post date:** [February 8, 2010, 8:12pm UTC](https://www.ruby-forum.com/t/documentation-conventions/183130/3 "2010-02-08T20:12:42Z")
Marnen Laibow-Koser wrote: > Marvin Gülker wrote: > > > Hi there, > > I’ve been searching the web for some time now, but I can’t find any > > reasonable conventions on how to write Ruby documentations. There are > > some pages out there describing what’s the best way to write Ruby source > > code, but if they cover documentation, they do it in just a very raw > > way, not going into depth. > > Look at the libraries you’re using. You’ll see that virtually everybody > uses RDoc. Problem solved. > > Best, > – > Marnen Laibow-Koser > [http://www.marnen.org](http://www.marnen.org) > removed\_email\_address@domain.invalid That’s true, but I’ve also read at more than one time that the documentation of many libraries is not sufficient, because they don’t contain enough information. I’ve been pointed to YARDOC when I asked, but that doesn’t fit my needs as I stated already (maybe I simply dislike that @ tags 🙂 ) Marvin ---
**Author:** ![quintus](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/q/49beb7/32.png) [@quintus](https://www.ruby-forum.com/u/quintus)\ **Post date:** [February 8, 2010, 8:15pm UTC](https://www.ruby-forum.com/t/documentation-conventions/183130/4 "2010-02-08T20:15:29Z")
Marvin Gülker wrote: > Marnen Laibow-Koser wrote: > > > Marvin Gülker wrote: > > > > > Hi there, > > > I’ve been searching the web for some time now, but I can’t find any > > > reasonable conventions on how to write Ruby documentations. There are > > > some pages out there describing what’s the best way to write Ruby source > > > code, but if they cover documentation, they do it in just a very raw > > > way, not going into depth. > > > > Look at the libraries you’re using. You’ll see that virtually everybody > > uses RDoc. Problem solved. > > > > Best, > > – > > Marnen Laibow-Koser > > [http://www.marnen.org](http://www.marnen.org) > > removed\_email\_address@domain.invalid > > That’s true, but I’ve also read at more than one time that the > documentation of many libraries is not sufficient, because they don’t > contain enough information. So write the extra information. This a docs-writing issue, not a technological one. > I’ve been pointed to YARDOC when I asked, > but that doesn’t fit my needs as I stated already (maybe I simply > dislike that @ tags 🙂 ) > > Marvin Best, – Marnen Laibow-Koser [http://www.marnen.org](http://www.marnen.org) removed\_email\_address@domain.invalid