From: Marcus B. <ma...@la...> - 2006-02-17 00:09:28
|
Hi... mkrz wrote: > The problem is, I find > the current state of the documentation so confusing that it makes me > feel really desperate, because I simply don't even know where to begin. Yes it is a mess. It has kind of grown willy nilly. The definitive version is the one in the SimpleTest project CVS tree. This can be found at... simpletest/docs/source/en/ However, some tutorial stuff is mixed in. If you look at the SimpleTest tarball, you will see the docs folder contains some bundled pages. These are the core documentation. They will differ slightly from the CVS version as adjustments are made. > - There are currently at least 4 different places that contain > SimpleTest related material. Sometimes overlapping, sometimes unique to > that place: > > 1) Marcus' own site www.lastcraft.com This is definitive, but usually set to the last released tarball. The latest CVS version may differ slightly. > 2) simpletest.org This is the PHPDocs API build by Jason. This is generated from source comments from the code and is really for developers hacking SimpleTest only. > 3) the SF site: http://sourceforge.net/projects/simpletest That's the SF page, right? Or do you mean the "home" link? > 4) The wiki on SF: http://simpletest.sourceforge.net/wiki/ This is Perrick's latest build. I don't know which tagged version he used, or whether it was from a random CVS checkout. There is also: 5) The bundled documentation. > > - If you don't know where it is, you can't find the wiki (at least I > couldn't without looking it up on this list). I think Perrick is still putting the material together. Even the decision to use a wiki may be reviewed. We may also be switching to a donated server. > > - the title for the page http://www.lastcraft.com/simple_test.php says > "Download the SimpleTest testing framework" - but it's not a download > page. The download link is buried in the upper right corner. Yeah. The title should probably not be changed, but the content shoudl be clearer. It's really chosen for someone searching for "download simpletest" on Google and historically was the download point. Because of the Google PR it's probably better to improve the page text than to move it. > > - The page http://www.lastcraft.com/simple_test.php is referred to as > "the documentation". On the other hand, that section contains an > "introductory example". Then there's also a "tutorial" under "PHP unit > testing". What really the is the difference between those two areas? > This is totally unclear to me, as they are very similar in stile. I wrote the php unit test tutorial before I wrote SimpleTest. The task was not to cover the features, but to provide a single real world testing problem. Unfortunately I am a bit of a one trick pony when writing, so the documentation ended up looking like a tutorial as well. The original material, the "php unit testing" one, will shortly be split into two sections and a third section added. These will be "TDD introduction", "Mock objects", "Working with legacy code". As soon as the 1.0.1 final release is done, I'll be tackling this. The "documentation" will stay pretty much as it is, but will gradually become more thorough. I have a whole bunch of features in SimpleTest which are currently either undocumented or still so alpha that I want to play with them some more before going public. These range from running tests in a separate process to scanning for test cases automatically. These will dribble out to the docs over the next month. It should eventually look a lot more like documentation. The documentation includes two one page guides. One is a quickstart one page summary (unit test, group test, mocks, web tester), the other is an overview and includes a roadmap. These do overlap, but serve different purposes. The one page quickstart is for people who have used JUnit and want to hit the ground running. The overview/roadmap is for someone who is not going to download, but wants a quick assessment of features. > > - if you call up http://www.simpletest.org/, you find the "actual" > documentation for all classes etc - and nothing else. Shouldn't the wiki > be here? The "table of contents" in the class docs contains a link to > the first sub topic, "What is SimpleTest". The link contains the word > "tutorial"... ??? Yes. It has yet to be moved, but progress is now being made. A much more comprehensive site is going to be put together. SimpleTest's success was something of a surprise to me (if I ever got 300 downloads a month I was going to be very happy). This has left me struggling to catch up. > 1) There should be only 2 sites for SimpleTest: the SF project and > www.simpletest.org All of the sites are currently code generated. I think the SF site should redirect to simpletest.org, and hopefully something like trac can replace the horrible SF bug tracker. > > 2) Remove all content from all other places to avoid duplication and > inconsistency. For example, wouldn't it be sufficient for Marcus' site > (lastcraft.com) to mention the project and link to simpletest.org for > all other purposes? Too many links point at the lastcraft site. I can't really start a migration until there is a replacement site up and running. That will be simpletest.org (which is why I bought that domain). Also Perrick gets value within the French development community for having those translations on his site. Although good for SimpleTest to trim stuff down, I also have a wider goal of boosting the reputations of those that have helped. You and me included of course. > > 3) *Clearly* differentiate between a) framework Help, FAQ and similar > stuff, b) framework tutorials, c) introductory articles on unit testing > in general, and d) Software (class) documentation and offer all of this > on ONE site. I think what the wiki contains right now and how the > material is categorized there is already a step in the right direction. Exactly. This will be the one ring to rule them all. Once up, the other sites can act as pointers. The simpletest.org site is still at early stages and needs a serious facelift before it can become definitive. Especially as I want SimpleTest helpers to derive consultancy value from the site. > I'm sorry, I don't want to flame or belittle the magnificent results > that have been reached so far. SimpleTest is absolutely great. It's just > that I'm confused and I have a hunch that other people will feel the > same if they discover SimpleTest. I absolutely agree with you :). I am sure Steve, Travis, Jason and Perrick do too. Unfortunately, I am wholly involved in working on the core, so have not supplied sufficient direction. This is definitely my fault. I am starting to get involved much more in the wider goals, and having Perrick in charge of the site was obviously a step in the right direction. The site will eventually get a proper FAQ, a consultants list, a list of resources and other things. I'd like to do all of this during this year. > > Best regards, > > Michael K. yours, Marcus -- Marcus Baker, ma...@la... - http://www.lastcraft.com/ PHP London every first Thursday - http://www.phplondon.org/ |