the blog
Back to -Blog

Ruby In Steel On Rails - the joys of documentation

From writing code to writing user guides...
by Huw Collingbourne
Wednesday 5 July 2006.

We’ve been working hard on Steel 0.7 over the past month. This release has a great many new features aimed at database development using Rails. Here’s a sneak preview of just one or two of the new things...

Of course, every new feature we add is a new feature that has to be documented...

Every minute I spend on documentation is a minute lost to software development. Well, anyway, that’s how it feels sometimes.

Only one answer then: get up earlier, go to bed later and cancel all those time-wasting little moments of life like, well, eating and sleeping…

Seriously, though, while the documentation of Steel is proving to be en exceptionally time consuming process, it is something which we are taking very seriously. I for one have had many experiences of running into dead-ends with other people’s software due to the fact that I just can’t figure out what button to click, which menu item to select or what information to enter into some dialog box or other.

Programmers, on the whole, don’t like writing documentation. However, users often do like to have the option of reading some…

As with the software itself, the documentation of Steel is currently very much in the beta stage. Moreover, as changes are made to Steel, corresponding changes have to be made to the documentation. At times, the software and its documentation may get a bit ‘out of synch’. In fact, that is happening to some extent at the moment. I am currently in the process of updating the old documents relating to the last beta (0.6) so that they reflect the features of the new version (0.7). There’s just one flaw in all this. At the time of writing the new version is installed here on my PC but it isn’t yet available for download. It’s pretty much ready to go but, along with the documentation, we are also going through a long process of testing. This too, at times, feels like a terrible waste of time – well, software developers are just like that: they prefer to be doing interesting things such as developing instead of tedious thing such as (yawn) testing. Or (snore…) documenting…

Anyway, just to bring you up to date. The new and revised documentation can currently be accessed online at the following links:

- Download Ruby In Steel
- Installing Ruby In Steel
- Two Minute Guide To Steel
- The Editor and Console
- Debugging Ruby

You will notice that there are some minor changes to the installation guide, reflecting the setup procedure for Steel 0.7. If you want a preview of what’s coming in Steel 0.7 you may want to check back in a day or two as we shall shortly be adding a Guide To Rails Development in Steel – this being the major addition to the forthcoming release.

Anyway, I can’t afford any more time on this blog. After all, there’s documentation to be done…

Bookmark and Share   Keywords:  ide
© SapphireSteel Software 2014