Jump to content

The ultimate community for Ruby on Rails developers.


Photo

What are documentation best practices for rails apps?

documentation

  • Please log in to reply
2 replies to this topic

#1 obirails

obirails

    Passenger

  • Members
  • 2 posts

Posted 23 October 2013 - 09:51 PM

Hi all,

My role at my job is evolving away from rails dev and into a completely
different field and I have been asked to document my rails app so that
others can maintain/enhance it in the future. What are the best ways to
document a rails project so that others in the community could pick up
my app quickly and easily?

A brief description of my app: I have been developing and maintaining an
internal rails app for my firm (a small twenty person finance company
where I am the only programmer) for about three years now. This app
generates reporting and support data for a wide variety of functions for
various people across the firm. The reports are generated by about
twenty different rake tasks that are set up via cron jobs to run
throughout the day.

I was planning on just rdoc'ing everything as well as possible, and then
writing a manual in Word to accompany it, maybe with pictures and
diagrams.

So - what is the best way to document a rails project?

Best,
M



#2 Rowel

Rowel

    Controller

  • Members
  • 109 posts

Posted 24 October 2013 - 03:51 PM

I have been asked to document my rails app so that
others can maintain/enhance it in the future

...a small twenty person finance company

where I am the only programmer) for about three years now

 

Oh oh.... I hope that you're now finished with the program, they're not planning to let you go once you finished the documentation.

.. asking you to document it so the future contractor hired to add a new feature would know what he's working on. 

 

I'd say, do a sufficient good job of commenting source code so that you can remember what/why you did, and let the Ruby source code speaks for the rest.  

Maybe a "technical" looking flowchart (that basically is the same logic as someone looking at the source) will figure out anyways. The flowchart is for show to the other financial guys. :)  State the obvious. 

 

Do a good job but not too good. :) 

 

(reminds me of a small-engine factory (which I shall keep nameless) whose management asked its workers to explain and train some visiting Chinese people on their workflow and assembly steps for the engine... a few months down the road, this USA factory closed down and the Chinese counterpart went online. )  


  • obirails likes this

#3 obirails

obirails

    Passenger

  • Members
  • 2 posts

Posted 25 October 2013 - 01:37 PM

Thanks!  I really appreciate it.  






0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users