Selenium: I have to say, your homepage's documents really suck.

[naco-siren]

With due respect, really, really suck.

[lmtierney]

Hi, thank you for your thoughtful and constructive comment. Did you know that this project is open source created completely from volunteers? You could be one of those people! There is an ongoing effort to create new documentation and it needs support. Please feel free to contribute here: https://github.com/SeleniumHQ/docs

[cgoldberg]

I have to say, your homepage's documents really suck.
With due respect, really, really suck.

I somewhat agree with the OP's assertion that the docs on http://www.seleniumhq.org/ are less than umm... good.

But my immediate emotional response is:
Welcome to FOSS! If RTFM isn't helping, you can always UTSL!"

@naco-siren:
pro-tip: leave out "with due respect" next time and just get right into your troll. Also the third "really" was overkill. You're trying too hard man :)

as always... this is a community producing Free Open Source Software.... Pull Requests are welcome! Come join.

[cgoldberg]

I have to say, your homepage's documents really suck.
With due respect, really, really suck.

On a more serious note

I'm sure the OP was drive-by troll exasperated in frustration. But, if that experience is common, maybe a constructive conversation about the docs on seleniumhq.org is needed? (If that is already underway somewhere, please send me off and ignore the rest of this post :)

The docs at http://www.seleniumhq.org/ are indeed lacking and are woefully out of sync with the current state of the codebase (yet somehow newbies seem to consistently onboard themselves successfully).

This is perhaps because the project has spawned a nice little collection of authors and training services who produce their own learning material. In a quick Amazon search, I see 63 books available solely about "Selenium Webdriver". That's pretty good! If you add on the dozens of training courses and the materials they produce, the Selenium user groups and archives, and thousands of StackOverflow questions/answers... that's a big honkin' load of resources you can learn from! Arguably, much better and broader than anything the Selenium project volunteers could cobble together on their own.

We should do less

I would love to see a PR that removes about 90% of what's currently published on the seleniumhq.org site. The docs there are much too ambitious, trying to handle stuff like best-practices, test design patterns, test philosophy, etc.

In my ideal world, for a project this size, documentation maintained by the project would just be very minimal "getting started guides" for each supported language binding. Most (all?) official client bindings already have auto-generated API docs that are published and we can link to. Maybe include a brief explanation of the high level architecture, and then a few links to the API docs, and that's all. Beyond that, let the commercial documentation (books/training material) fill the gap of hand-holding newbies and teaching proper testing.

Any contributor's time spent writing/maintaining docs, is time taken away from what could otherwise have been spent fixing bugs, adding features, writing internal unit/integration tests, and keeping compatibility with the ever-changing browser landscape. Considering the disproportionate size of users to contributors, I don't really want much time spent by developers maintaining prose explanations on tangential testing subjects to hand-hold newbie end-users.

The repo's source code is generally well structured and pretty readable. Beyond that, The test suites are pretty comprehensive (which trumps good docs anyday in my book) and can be used to understand how various parts of the API actually work. Beyond that, the healthy FOSS ecosystem around this project is already providing opportunities for 3rd party technical writers to write commercial or free (one can wish) books for the newb case.

- just my $.02

---

p.s. I'm not even a project maintainer... just a lowly contributor with a few commits to the selenium repo under my belt... and a veteran user with a vested interest in keeping Selenium Webdriver rocking :)

p.s.s. I can take a crack at a PR to the docs repo with my ideas (once some time frees up)