Comments on: 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.
30 Comments Comments:
Vic7
17-Aug-2010 16:02:33 |
...its a Wiki afterall. I did loose sight of that. I've found the odd typo in the documentation, same as any other documentation. The docs are now better than most though.
Point being, the Wiki is described as being "written by experts". So, I would be dissuaded from contributing to the Wiki even if I were to recall it was a Wiki, - being but a clumsy hobbyist at best. But one does not have to be an expert to point out the odd miss.
I could own a page though. I could say, monitor the posts to do.html
or maybe a few more pages. Maybe others might adopt a page themselves - and release it or get other pages every 6 months or so.
Thus the work of the editing of the pages could be distributed.
So, maybe "Editor" could be added to the bottom of the page, and where no one has yet to volunteer, it could read "Position Vacant". And although a page may read "Written By Experts" it could also actively solicit change from interested persons via the wiki.
Free time, slack time....is necessary. One could run a marathon every day. But without a week or so of slack time to recover - for how long?
| Graham
17-Aug-2010 16:43:02 |
It'a wiki which no one has write access to ... | Gregg Irwin
17-Aug-2010 17:55:31 |
I don't have an account either AFAIK, and I don't want to manually edit wiki pages that can be generated via reflection and added REBOL data.
I greatly appreciate your efforts to update things Carl.
| Carl Sassenrath
17-Aug-2010 17:57:35 |
Vic7: Yes... but perhaps we can do that by allowing user comments to be posted to any page? Then, when desired, relevant comments can be rolled back into the main content of the pages.
Graham: I was expecting that comment, but it's not entirely true. Most of the REBOL experts who are on R3 DevBase Chat have write access to this wiki (including you, Graham.)
The R3 chat system provides the authentication system for this wiki. If it seems more strict than the REBOL.net wiki, it is, and for what should be obvious reasons.
| Endo
18-Aug-2010 5:27:09 |
Very good updates, thanks a lot.
I know R2 is getting obsolete but I would like to see R2 Dictionary (http://www.rebol.com/docs/dictionary.html) document updated.
At least newly added functions like ajoin, spec-of, read-cgi etc. can be added. | Steven White
18-Aug-2010 6:33:34 |
You have pointed out an interesting situation.
I myself personally LIKE to write documentation. I have complained about the lack of it for REBOL (usually related to VIEW). I would be happy to make a contribution, BUT, I don't know how the stuff really works in the first place. I need the documentation to understand it, but if I had that, then it obviously would already be documented. What to do. I have no idea.
However, one thing does come to mind. It came to mind because recently I was looking over the cookbook (or somewhere like that) and I found a tip on how to do something. This something was something I had asked the mailing list about some time ago. The mailing list gave me an idea that worked, but it was a bit convoluted. This new and better way relied on a different function, and on an option in that function that I had not known about.
So putting it all together, I wonder if this idea would work. What if you could find a hundred people, each to write a detailed description of one function. A person would dive into that function and learn all about it, through reading other documentation, through experimenting. He would have existing documentation as a starting point, and then would go on, through his own efforts, to become an expert on that one function. Then he would write about it. He would tidy up (if necessary) the existing documentation from the dictionary. Then he would expand on it with a large number of examples (the ones he created when trying to understand the function). And finally, he would write a section explaining why one might us this function, what one might do with it. That's an area I would have found useful in certain situations in the past.
In summary, you would have documentation written by people who don't know REBOL, but who do, by their own efforts, know one little piece of REBOL very well. I probably should write up a proof of concept on this. I think I could do it for a couple functions, but maybe I would get just so far and then hit a wall.
Another thought, could we clone Carl. Or, failing that, could he adopt the "extreme programming" way of working, where two people sit at one computer. In this case, those two people would be Carl and a documenter. The documenter is there for the creation of REBOL, and notes how things work, why the work the way they do, what problems are being solved by various funtions, and so on. Then he writes the documentation as REBOL itself is being written.
There have been a few cases now where I have beaten my head trying to do something in REBOL, and after much anguish come up with a solution, and found it to be only a few lines of code. I would like that not to happen so much. | Henrik
18-Aug-2010 8:23:22 |
I was actually updating that particular function reference last year, but lost time to do it, so it has not been sitting entirely still. Some pages were updated quite a bit. But don't underestimate the time it takes to go through it. It took me the better part of a week to work through the first 20% of the function list. | Carl Sassenrath
18-Aug-2010 8:52:53 |
Endo: Yes, the R2 docs need updating as well. I was asking earlier about merging R3 and R2 into a single database. I think that is the only practical long term way to maintain it. (Tags would pick the correct details for R2 vs R3, but most of the text would be common to both.)
Steven: Perhaps adding a commenting method will make your suggestion possible. Such an activity could be independently coordinated.
Henrik: Yes, I noticed, thanks!
Another idea:
Many beginners want to know how to do basic things. With that in mind, I created the Cookbook contributed publication area of the site. I'm not sure that I got it quite right, but it was headed in the right direction. What I would like to see is a revised form of the cookbook called "How To Do" with a good index sorted by subject. For example, "How to manage a small data set" or "How to save an object to a file."
Those of us who are experts use common patterns in our programs, but we don't take time to educate others on how and why we use those patterns. That's the kind of information that is valuable to many new users.
| sqlab
19-Aug-2010 4:01:46 |
I tried to update http://www.rebol.com/r3/docs/functions/encode.html and ../decode with system/codecs instead of system/catalog/codecs.
no luck .. | blazs
19-Aug-2010 7:17:13 |
Those of us who are experts use common patterns in our programs, but we don't take time to educate others on how and why we use those patterns. That's the kind of information that is valuable to many new users.
Maybe something along the lines of the patterns available for C++, Java and Smalltalk, all of which have had books written about them. Would it be beneficial to start up a 'Patterns' wiki?
| Graham
19-Aug-2010 18:41:11 |
(at)Carl .. if you were referring to http://www.rebol.com/r3/docs/functions.html and their sub-pages, then no, my R3Chat credentials do not grant me edit access.
| Ladislav
20-Aug-2010 14:54:26 |
Graham is right, Carl. Nobody has the access currently. It seems, that you have forgotten, that the changes disabled login for people. And, not only I, but other people too were waiting to put in their changes. | Ladislav
21-Aug-2010 1:21:18 |
Sorry, I stand corrected. Did not read the message #6921 in R3 Chat. | Graham
22-Aug-2010 20:13:21 |
So, the restriction is that you have to have a rank of greater than 50. I count 6 people including Carl and his wife who satisfy that criterion. Even Gabriele is denied write access. No wonder your fantasy never eventuated!
| Florin
22-Aug-2010 22:07:11 |
Aug 23, 2009 - Last post on reboltutorial.com
Nov .., 2008 - Last post on dobeash.com
| sqlab
23-Aug-2010 10:40:17 |
50 is enough, following the instructions in #6921 works. | Kaj
24-Aug-2010 1:39:24 |
Florin, don't worry. Dobeash is busy enough, among other things with running in the Australian election. :-) | shadwolf
29-Aug-2010 10:29:16 |
If it was really a problem of writing access people could simply make an account on http://www.rebolfrance.info/
create the doccuments needed then say to Carl "Hey !!! Look fantasy boy we have all that documentation all ready for you"
But no ... it's better to stay still and whine like puppies.. Or is it our French wiki isn't good enough for you ?
Solutions exists to any problem but when people are definitly lazy and lacking interest then it's obvious nothing emerge.
| Vic7
29-Aug-2010 17:51:44 |
Collecting comments to a page and considering them for periodic page edits sounds good. Maybe the link set there with "Edit" & "History" at the top right of the page. Or something more prominent to remind readers that comments are welcome.
Including R2 & R3 in the same documentation is good. It provides a transition to for experienced users. R2 was great and always will be, even if R3 is better. I hope R2 can be maintained for some time to come.
R2 references could always be removed from R3 documentation at a later date if desired.
The "How To" section would be an interesting read, alternative solutions could be encouraged. | Luis.
2-Sep-2010 2:07:40 |
(at)Kaj: Regardless, looking at the comment from Florin reminds me of the impression I keep on getting when trying to gather more info.
Example: Posted in RebolWeek, February (this year one presumes...) is the mention of 'Dobeash meets REBOL/3' with 'More soon. Docs pending ... and Dobeash does docs
'. So you follow the Dobeash link and...cobwebs.
No mention of running for any elections...!
The only site that has never dissapointed is Nicks at www.re-bol.com
Cheers,
Luis.
| Kaj
2-Sep-2010 6:38:30 |
That's one side of the medal. The other side is that Dobeash has recently announced new REBOL libraries for building modern websites, that he is testing on his election website.
The world is not perfect. This is one of those things where people's opinions tell more about their character than about the subject matter. You can view these patterns as a glass-half-full person or as a glass-half-empty person. | Luis.
3-Sep-2010 2:15:06 |
(at)Kaj: /quote'This is one of those things where people's opinions tell more about their character than about the subject matter.'/quote
Well, that, as you say is also another side of the coin: That someone is ready to prejudge character on a website Comment Post...
The fact remains that unless you've been here for a while you don't get an impression of the progress, whether for Rebol or third party projects. Anyone passing through will not get a good impression, this has been brought up many times and goes to show our concern for these projects.
It's a little better now that the Rebol front page tags new items. But look at the Softinnov site, check the dates: Now, if you 'know' Softinnov the you know to go to cheyenne-server.org (or the last link on the left of their site) to get the latest on Cheyenne.
My glass is half empty because someone changed the other half to vapour...
Cheers,
Luis.
| Graham
3-Sep-2010 23:21:36 |
Hmm. Cheyenne's SVN was only updated 11 hours ago to accommodate changes in the web socket specs.
| Luis.
6-Sep-2010 1:24:28 |
(at)Graham: As I said 'Anyone passing through will not get a good impression'. Checking the SVN isn't 'passing through'...
When you see rotten fruit in the basket, you're not tempted to check if there is fresh fruit underneath.
Cheers,
Luis.
| Kaj
6-Sep-2010 3:58:59 |
I was trying to bring you good news, but if you don't want it, we can't help you. | Luis.
7-Sep-2010 1:52:30 |
Never said I didn't want it.
The issue is that it's not where you'd expect it to be.
That was very clear.
Cheers,
Luis.
| Kaj
7-Sep-2010 10:11:47 |
Seems like you have two options: changing the news or changing your expectations. | Luis.
8-Sep-2010 2:07:05 |
Expectations change based on the available news.
The news is not under my control.
Cheers,
Luis.
| Kaj
8-Sep-2010 5:18:36 |
That's good. Personally, I have chosen to change the news: http://syllable.org. | meijeru
10-Sep-2010 9:48:32 |
Was updatng some doc pages, and got stuck being unable to have a line starting with : (in order to give an example of a set-path). Does makedoc have a superquote? |
Post a Comment:
You can post a comment here. Keep it on-topic.
|
