the blog
Back to -Blog

Documenting Ruby In Steel 1.1

Got A Request? Please Let Us Know...
by Huw Collingbourne
Monday 16 April 2007.

We are nearing the release of version 1.1 of Ruby In Steel Developer and the time has come to update the documentation and help files...

The Ruby Editor; the RHTML Editor; Ruby On Rails Tools; the Debugger(s), options, widgets, importers, converters, macros and snippets... many of these have been updated and the documentation for all of them has to be re-checked and, in many cases, re-written.

I would be the first to admit that documenting is not the most interesting job in the world. But it is extremely important. From personal experience, I know how frustrating it can be to try to grapple with some unfamiliar piece of software which either has no documentation at all or has documentation that is incomplete or inaccurate.

The manual supplied with version the version 1.0 release of Ruby In Steel runs to 66 illustrated pages. There are also a number of separate documents (supplied with the Developer Edition) covering the Ruby In Steel Macro Library, the Ruby Snippet Editor and the LightTPD server. The integrated help system duplicates most of this information in a cross-referenced, hyperlinked form.

While a version 1.1 update probably doesn’t sound like much, it is enough to require a complete revision of the documentation and help system. There are several significant changes that need to be documented: using the Mongrel and WEBrick servers to debug Rails applications, for instance, the addition of drill-down debugging inside the code editor, a few slick new user interface thinggies (yet to be announced - we’ll give more details here on the Blog shortly) and so on. And there are numerous minor changes too: an extra option here, a new property there. All of which have to be documented.

Once the ‘essential documentation’ is complete, I plan to move on to the non-essential but really-nice-to-have stuff: ‘How-To’s and tutorials. It’s my impression, for example, that many users don’t realise just how configurable the IDE is - how all the colours and fonts can be changed; how to save and load up custom settings; how to customize features using our macro library; how to create Ruby auto-expand and auto-surround snippets and so on...

Maybe there are other things that you’d like explained in more detail too? If so, please let us know. I am making the documentation of Ruby In Steel one of our highest priorities - second only to developing the software itself - and I would welcome feedback, comments and requests so that we can continue to improve the core documentation and also to create tutorials to help you get the most from our software...

Bookmark and Share   Keywords:  news
© SapphireSteel Software 2014