Hi Red5 Team - This is my first post to the list, and I am just a bystander, but I've been reading the lists for quite some time. Like everyone else, I'm in awe of all the work being accomplished, and totally excited by the prospect of an open-source alternative to FCS/FMS. I'm creating a classroom app, and I want to use Red5.
The first reason I am speaking up now is because I want to applaud the efforts of members of your team to expand the documentation beyond the API and a few Getting Started guides. It is really good to see voices speaking up for consistency and for context. By context, I mean taking the time to explain a lot more of the terminology and concepts that, if left unexplained, will only prevent or delay otherwise intelligent, capable, and interested people from approaching Red5 (read: me - at least, I'd like to think so). The second reason I am writing is that I am a little disappointed by the state of the docs as of 0.6RC1, and I want to offer some (possibly obvious) suggestions. One of your goals is, I believe, to make Red5 easy to use. Speaking as one who did the "everything but the API" documentation for Smalltalk / Java class libraries for about 10 years (1993-2002), I can speak with a little experience. I believe it's critical that the docs have the involvement of both newbies and experts. Obviously, the API requires programmer-level understanding and experience. However, I'll contend that much of the rest of the docs does not. I myself used to be a non-programmer when I was doing docs. Despite this (or maybe because of it), my docs got kudos from a lot of customers. One customer at General Dynamics remarked to one of our company's sales people that the docs I wrote were the best she had ever seen. Point made. I'm not here to talk about me. I just want to suggest that if the team wants Red5 to end up engaging a larger audience, those with expertise should expect to act regularly as info-providers and reviewers for the documentation authors. And for their part, at least some of the doc authors ought to be folks with **LESS** experience who are passionate enough about explaining stuff that they will be willing to bug the programmers and domain experts about both basic and advanced info, without fear, until they fully understand what they're writing about. It's not a waste of time to do this -- it's actually a somewhat non-intuitive quality assurance process. If only those with expertise are allowed to write the docs, or if they fail to communicate with the doc authors adequately, my experience tells me that the docs will be full of gaps and assumptions made about what readers know (or should know), and Red5 will risk forfeiting much of its potential audience. And perhaps some 5-star reviews as well. On the other hand, if including some talented (non-programmer) communicators on the doc team is feasible, I think you will only increase your chances of surprising people with Red5 docs that are superior to 90% of what's out there now for other software products. **EFFECTIVE COMMUNICATION** is the GOAL (i.e., with your USER AUDIENCE, or if you are one of the programmers, this should mean: with your DOCUMENTATION AUTHORS). Suggestion: It may make sense to have a "doc" mailing list for your documentation effort, separate from the "devs" list. I want to add that I was really happy to see the empty table of contents on the wiki, both from the standpoint of recognizing its role in the documentation process and from the standpoint of someone who wants to see all the sections filled in as soon as possible. It is a great way to get everything and everyone "on the same page", so to speak, and I hope that it will stimulate the more experienced team members to start tearing into it. If the present wiki infrastructure is too unmanageable or problematic to hold up under the weight of this, then by all means change to something better. Maybe a periodic review and feedback cycle, instead of an all-out wiki approach. Okay, that's it. Please take this as food for thought, if nothing else. I believe you guys ARE getting it right, and hence, I am really looking forward to what's coming (just give me some real docs!). Applause and compliments and gratitude to **ALL** of you, to be sure. Cheers, Steve Kladstrup _______________________________________________ Red5 mailing list [email protected] http://osflash.org/mailman/listinfo/red5_osflash.org
