I've seen worse documentation :) there are some step-by-step examples
to get you started and for everyting else we have subversion access. I
was rather put off by the amount of "interface documentation" I found
in the wiki.
Something I find very disturbing is that you talk about "hash"es when
really you mean JS objects. You should fix this. It doesn't really
improve credibility when you want to "sell" me a JS library and mix up
fundamental nomenclature :)
"Everything is contained in a single anonymous base hash {}" [1]
That annoyed me so much that I can present you a patch for that
particular wiki page, see attached. If you are interested, I would fix
this for all wiki pages.
greetings,
simon
[1] http://code.google.com/p/simile-widgets/wiki/Timeline_EventSources
On Feb 11, 4:12 pm, Larry Kluger <[email protected]> wrote:
> 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.
> Seehttp://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
-~----------~----~----~----~------~----~------~--~---
