 |
Function Descripton Updates
As you know the REBOL 3.0 documentation contains a newer Function Reference section. Although the HTML page layout was cleaned up, most of the descriptions were simply carried-over from R2. Secretly, I had hoped that some brilliant aspiring author would come along and update all the function descriptions... so I wouldn't need to. (It is a Wiki, after all.) Wow, was that a fantasy. Well, I'm not surprised that very little happened. It is a large and difficult task. As the original author of the REBOL Dictionary, I can tell you that it's not any fun at all. And, rare is the technical author who understands both code and how to write docs well. My hopes were set too high. However, I think I've found a solution. Remember my "Documentation Fridays" promise? Nope, sorry, that's not the solution. Forget that idea. I'm always too busy to set aside an entire day like that. Instead, I've begun slack-time utilization. What's that mean? System software design and implementation is a difficult process. You don't just sit down and bang out a few lines. No, it normally takes a couple hours to become fully immersed within the matrix of variables and functions... then you work for as long as you can, until some other event occurs, or you fall asleep. But, frequently during the week there are little time periods where there's not enough time to dive into system code, but you can, if so inclined, hammer out a few doc paragraphs or examples. That's slack time. These days, when a few minutes of slack time pop up, I've been filling-in the blanks on the function description pages. Also, I must admit that I was inspired by the positive feedback I received on the Quick Reference Card. That, and the fact that I looked at the card and started clicking on some of the function links... only to discover "wow, that function is poorly documented." (Not my exact words.) That got me going. So, now, in those few minutes right before lunch, or just after sending some emails, or before retiring for the night, I've been extending the function documentation. I'm following the links from the reference card to start. That's manageable and progress is happening without it taking time from important system development work. To see what functions have been updated, just go to the R3 Documentation page, where I've linked to the most recent changes. I hope you find these small updates useful. I expect many new users may as well.
|
 |
Updated 12-Nov-2024 - Copyright Carl Sassenrath - WWW.REBOL.COM - Edit - Blogger Source Code |