I received the following private message (below). The author said that I could respond on the public list, so here goes...
~~~~~~~~~~~~~~ I think your problems and complaints (below) with the documentation are not unreasonable and are shared by many people who could benefit from Exhibit, Timeline and other Simile projects. In addition, your issues are also applicable to many other open source projects, so it is also helpful to see how other projects have tackled the same problems. Both Exhibit and Timeline are terrific projects and have very solid code bases. Both benefit from being the second version of software, built on the experience from Timeline ver 1. That's all good news. More good news for the Simile projects is that there are examples, some amount of documentation and an active support community available via this Google group. The not-as-good news is the documentation could and should be better. Generally speaking, there are two types of documentation: reference and cookbook. Most documentation written by developers falls into the reference category, solving the problem of "I know what I want to do, I just need some details on how to do it." Much of the Timeline documentation is reference material. What you need is cookbook documentation. -- And an additional issue for the Timeline docs is that much of it refers to ver 1 of the software. Sigh. Cookbook documentation answers the question "Show me how to do something nstep by step, so I can then do it for myself" One way of providing cookbook documentation is through examples. I have put time into adding more examples to Timeline since the examples can be used as cookbook documentation and are also used as regression tests to help ensure that changes to the Timeline source don't break existing software. But pure cookbook recipies are also needed. Other open source projects use screencasts as the first level of documentation and I plan to do the same. My first screencast for the Timeline community, about debugging on Firefox, was well received, so I plan to record more. See http://sandbox.kluger.com/timeline_firebug/ In the meantime, please 1) Search the mailing lists for questions similar to your own 2) Use the examples! Get them running on your own machine, then modify them for your own needs. 3) Send additional questions to the mailing list. Regards, Larry ----- Forwarded Message ---- Sent: Thursday, February 5, 2009 10:57:23 AM Subject: Re: Documentation Hi Larry, Thanks for the welcome. I had actually already looked at both of those suggestions but I can't make heads or tails of them. I am somewhat new to the whole HTML and JavaScript world but I am an IT guy (databases are my specialty) and I know how to program. What I don't know is the server side implementation stuff that gets all of the web pages working. However, I am not convinced that I need to know that information to do this. I am doing this just to learn and I am applying it to something I enjoy as a way to learn. Being in the IT field I am woefully aware of the lack of good documentation for applications/software. I am guilty of it myself. And this may be different seeing as it is an open source project; something I have not been involved in before. Also, after reading some of the other posts, it seems like there are still a few bugs to be worked out. I have no problem with that either. But with the amount of code that has been written to support this there must be some formal or informal notes on how it works somewhere. I can't believe that I will have to read all the code to figure out how to change a theme. By the way, the text in the timeline-api.js file says to use the zip file but it doesn't say where to find the zip file. I copied everything from the simile v2.2.0 folder to my web server and changed what I thought I needed to change according to the NewThemes instructions but no matter what I change I see no difference on my screen. I know I probably sound like I am whining, and I probably am, and you are probably thinking "Do I really have to help this useless guy?" but I think the widget is extremely well thought out and I would like to use it. If you or anyone else could help me out it would be greatly appreciated. Would it be possible to chat maybe? I would rather waste as little of your time as possible so documentation would probably be better from your point of view but I might just be missing something simple. Thanks again. On Feb 4, 11:59 pm, Larry Kluger <[email protected]> wrote: > Hi, > > Information on running Timeline locally is in the timeline-api.js file > itself, > seehttp://simile-widgets.googlecode.com/svn/timeline/trunk/src/webapp/ap... > > Changing themes is documented > here:http://code.google.com/p/simile-widgets/wiki/Timeline_CreatingNewThemes > > I just re-wrote it (completely), so it is now correct. Let me know (via the > mailing list) if you have any problems. > > Regards and Welcome to Timeline! > > Larry > > ________________________________ > To: SIMILE Widgets <[email protected]> > Sent: Wednesday, February 4, 2009 9:53:07 PM > Subject: Documentation > > I am looking for more documentaion regarding the Timeline. > Specifically, how to run it locally and how to change the theme. It > seems these are somehow related topics. Any help would be greatly > appreciated. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "SIMILE Widgets" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/simile-widgets?hl=en -~----------~----~----~----~------~----~------~--~---
