Documentation

[myndzi]

I spent about 12 hours yesterday writing a program. I am writing this
by request to share my experience in the interests of helping advance
the documentation for this project. For context, I am no dummy - but I
have essentially no useful knowledge of Java or any of the other
languages supported by Selenium. I didn't really have much of a grasp
of object oriented programming until yesterday, at least not as Java
presents it. I do have a good understanding of programming in general,
as it relates to telling a computer how to get things done, and I am
technically savvy.

So, I stumbled into Selenium and saw that it looked like a very useful
thing that we could use to automate some processes that we currently
have employees doing manually. I decided to write that program. I
downloaded the Selenium IDE plugin for Firefox and gave that a spin.
Worked pretty good, but I determined fairly soon that it didn't
provide everything I needed and that I was going to have to get my
hands dirty.

I tried Python first since my brother wants to learn it. When I go to
a page that has a download link, and I click it, I expect to be taken
to a page where I can download the thing the page is about. In this
case, users are taken to a page that tells them to use a package
manager - and also provides a java application of all things for the
"Python" installation. After installing pip in order to install
Selenium and finding my way to a Python console, I managed to get it
to launch a browser window pretty quickly and things were looking
good. I had some difficulty locating the information necessary to do
anything useful, but it turns out I didn't have to do much of anything
- the example on the download page failed. The .get function
apparently stalled with no timeout after successfully launching a
browser window. Some Googling showed me a bug that people had
encountered with Firefox and the active frame, but the workaround
didn't work for me.

Researching further, I soon noticed that many of the code snippets on
the Selenium homepage under Documentation were only available in Java.
Since Python looked to have a critical flaw and I wasn't tied to any
particular language, I went and downloaded Eclipse. This time, the
download link downloads a Java library, but I don't know what to do
with it. A little looking shows me the Java instructions for Setting
Up a Selenium-WebDriver Project. Which tells me to go download some
other thing to use for a package manager, and it has me in notepad
pasting XML that I have to import to my Eclipse project - and this is
the "easiest way". I'll save my rants about Eclipse and Java in
general except to say this: if you were to imagine yourself in a
situation where you simply wanted to pop open an application, write
some code, and execute it - Eclipse and Java are about the furthest
possible thing from that goal that I can imagine. It would probably be
less complicated to start coding in assembler.

OK, so I get things working, and after spending a while figuring out
what the hell a package is and why I need to make three successive
hierarchial files (er, what do I name them all?!) before I can start
typing anything, I promptly make some errors I don't know how to
correct and nuke the project. Then I have trouble reproducing my work
with Maven. More searching, more trial and error, I eventually get
something I can use, and manage to take a combination of stuff from
the website and some exported code from the IDE as a starting point. I
quickly find out that Java doesn't like it if you don't do things
Java's way. I spend some more time learning about object oriented
programming.

Meanwhile, I've managed to launch a browser, located and used the
workaround to make it actually work (Oh yeah, did I mention that while
the site says it supports Firefox 8, it doesn't?), and have got some
basic stuff done. I spend most of the afternoon learning how to make
Java do what I want, and I'm coming to something that looks pretty
good. Now I just need to do a few simple Selenium things and I'll have
what I want---

Wait, how do I do those things? The "documentation" section of the
website is basically an introduction; light on the detail, heavy on
the exposition. It has neither a complete nor concise description of
the system. At high resolution in a windowed browser, It's a full page
before you get to any relevant information on WebDriver from the
documentation index. And that section is half the size of the IDE
plugin, which is arguably much less complex. More space is then
devoted to obsolete information and some design stuff.

I browse what seem to be the relevant sections, but don't find enough
information. After more Googling I find my way, ironically, to the
Download page on seleniumhq, which has a link to "JavaDoc" -
apparently documentation. It turns out that, while I'd gathered that
there were two major versions of Selenium and I ought to be using the
newest one, WebDriver, the JavaDoc makes no such distinction. It is
completely barebones, sparse with the information, and everything that
IS there is basically Java code anyway and doesn't tell me anything
useful. I spent a while trying to figure out, between seleniumhq and
javadoc, how to make the program wait for something specific. Sounds
simple, right?

I met a very helpful fellow on IRC who gave me a hand, and not wanting
any hand-holding, I asked what questions I thought would get me enough
information to work with and failed repeatedly. In fact, he seemed
unable to directly quote functional code when I finally did ask - and
he seemed to be quite familiar with the project. Maybe he's not a Java
programmer, I dunno; I certainly don't hold it against him.

Anyway, you may be able to tell that this was a rather frustrating
experience for me. I knew exactly what I wanted, I knew how to express
the logic in code - even if I didn't know the syntax of the language
involved - and I was unable to find the most basic information about
what I had to do in a form that was useful to me. After a little
venting on IRC and a look at the clock, I decided it was time to give
up for the night. Closing my tabs, I noted an example that looked like
it was exactly what I needed. I'll just quote it right here:

(new WebDriverWait(driver, 10)).until(new
ExpectedCondition<Boolean>() {
public Boolean apply(WebDriver d) {
return
d.getTitle().toLowerCase().startsWith("cheese!");
}
});

I was a bit flabbergasted; this didn't look anything like any normal
Java code I'd seen yet. After asking some more questions, I managed to
get most of a handle on what was going on and why and how it worked,
and I managed to summarize my thoughts on IRC:

"so we're making a new WebDriverWait object and not assigning it to
anything (it just gets destroyed when done with?); it is calling the
method "until", and as a parameter to "until" we have a new
ExpectedCondition object which extends some other thing by, i guess,
specifying a function that gets polled to determine success"

...to which the response was, "that's pretty much right"

Now, maybe to a Java programmer this makes sense immediately, but to
me it looks like nonsense. I think I may be able to get what I want
out of this whole thing tomorrow, but I've spent a good 12 hours on it
today for what was really a rather simple project. Now that I've
related my experience in brief and possibly inaccurate terms, I'd like
to share some thoughts about documentation.

To me, the quality of documentation has an inverse relationship to the
amount of knowledge needed to make proper use of it. To professional
Java programmers, the JavaDoc stuff may be perfectly adequate. And if
"perfectly adequate for professional Java programmers" is all you
strive for, there's no harm in that; I know what it's like to
volunteer your time for free. There are some things that could be
done, though, and some of them fairly easily, that could upgrade the
documentation from "adequate for professional Java programmers" to
something more like "great for professional Java programmers, and
accessible to utter newbies".

First and foremost, the prominent "Documentation" link at the top of
the site should take the user to actual Documentation. Not an intro,
not a Hello World, but a right proper manual. The manual should be
focused on current information and only current information
specifically about the library and its use.

The JavaDoc intermingling Selenium 1.0 and 2.0 calls with no obvious
disclaimer informing the user that "Hey, these commands are old and
you shouldn't try to use them!" would be good too. I don't really know
how it is with the other languages. It doesn't really matter if there
is suitable documentation that is NOT JavaDoc. The JavaDoc is like the
skeleton of some creature, with no organs or flesh or life in it. A
little English would go a long way there.

The downloads and instructions could do to be downloads and
instructions that can work out of the box, rather than dependent on
other stuff that must also be figured out and installed.

Finally, the potential Big Project. What is useful and possibly vital
to me is certainly useful and convenient to people more knowledgeable
than me. Proper organization of information from the perspective of a
person who is reading the documentation to gather necessary
information is key. There are two things I want from programming
documentation: one is to be able to find the command that does what I
want easily, and the other is to be able to find out what a command
does and how to properly use it easily. Neither of these goals are
satisfactorily fulfilled from my perspective.

For the first part, one must consider "what are the basic things that
people will want to do with this Selenium thing?" For starters, how
about Get Things Started. That deserves a page all on its own, with
sections from step-by-step instructions to take you from 0-to-writing-
code to the first basic things you must do to get that code to work.
What things to import/include/whatever, what statements to use, how to
initialize your shit.

Secondly, How To Make The Browser Do Stuff. Navigate to a page, click
a link, type text in a field, etc.

Thirdly, How To Control Program Flow, with information about how to
know when it's safe to send commands, how to wait for specific things
to happen, how to check for specific things, how to deal with popups,
confirmations, etc.

Finally, How To Deal With Errors; what kinds of errors can happen,
where and why they happen, common solutions to dealing with them.

That's just an off-the-top-of-my-head breakdown of what I consider to
be basic functionality. If I wanted to do something and I didn't know
how, I could easily narrow it down by choosing one of those broad
topics. Further, there are natural categories within those topics that
would narrow my search down to a list of functions I could skim to
readily find what seems most appropriate - particularly if they have
short, meaningful descriptions. Everything should be in these
categories, or these and some additional categories. Nothing should be
inaccessible from this top-down information-seeking perspective.

Once you make it down to a specific command, you've made it to the
other component of good documentation: describing what the command
does, how to use it, when to use it, what it's commonly used with, and
what commands are related/similar/useful in conjunction with it.

Code examples for everything are particularly useful, and more useful
if they explain why things are written the way they are or at least
make reference to terms that can be searched and learned about. This
is particularly applicable when the example code is convoluted -
though not writing convoluted things in the first place is
preferable.

Though this was written somewhat critically, I hope you guys
understand that I bear you no animosity, and please do with my
comments what you feel best. I wish you good fortune in your project
and continuing success.

[Mike]

All I can say is that I feel your pain.

I came to Selenium as something I was assigned at work to get familiar
with, but I could only spend an hour or two on per day, provided other
duties did not intrude. At the time the 2.x had not been released and
I was trying to work with 1.0.8 and found out that 2.0b2 was
available. Documentation on WebDriver was virtually non-existent,
although I knew it was supposed to "be the future". So I was bouncing
back and forth between the two by writing code that could run on
either one to determine which was best. Eventually compromising on
using 2.x with WebDriverBackSelenium for the majority of the code I
was writing.

You are perfectly correct about the Javadoc being inadequate. I have
submitted a couple of patches that have corrected errors in it now,
but those only touched the ones where the information was incorrect
(wrong or missing parameters or missing return info for the most
part). In many cases public methods I saw had no documentation at
all. In many cases (but not all) what was provided is less than
helpful. The only case I have run into worse Javadoc information is
TestNG, where they seem to excel at providing no useful information
int he documentation whatsoever.

If ever I have the time I would like to start doing a scrub of the
modules and work on updating the Javadoc for each, but right now I
really do not have the spare time. I do believe this would go a long
way to providing better information for developers.

As for the general documentation, it also needs to be worked on. I
started writing something more as notes to myself than anything as I
worked on getting Selenium up and running. It has turned into a
tutorial that people that covers how you set up your system, where to
get the files you need to install, how to use the IDE to record tests,
and finally how to take the output from those recordings and turn them
into useful tests. What I wrote is somewhat specific to our work
environment, but it could be generalized fairly easily. While I think
that the IDE is not needed by someone familiar with how Selenium
works, it is still a good training tool to help you get familiar with
how to write code, sort of like training wheels on your first
bicycle. For simple quick-and-easy tests it is actually a fast way to
get something done that works "good enough".

Unfortunately, I think many of the developers working on Selenium are
probably too close and too experienced with how it works to properly
document a beginners guide for it. When you know how something works
well enough it can be hard to remember how it is for someone that
doesn't know it and it approaching it for the first time. That is
just the way things work sometimes.

Mike

[Leo Laskin]

What I hear here is that the "getting started" documentation needs work.  I see a lot of complaining, but no fixes.  Submit patches, fixes.  Download the documentation trunk.  Edit it, resubmit it.  I know that there are lots of documentation commits on a nearly daily basis(if you hang in the chatroom you'll see this).  If you have questions which you can't figure out and don't want to do the above, write a blog post!  Tweet it, tag a Selenium developer.  Make a facebook post!  I assume that most of the people on this list have or know how to obtain a free blog.  That way when I(or others) have the same question, your blog post will be one of the first results, and we'll get our answer!

I want to remind everyone here(though most know) this is an open source, free app.  That means the developers aren't getting paid dime#1 for the time they spend on this.  What it is though, is an amazing tool for internet testing that supports currently popular(and even a couple of unpopular) languages with a vibrant community. Use your resources, people! 

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To post to this group, send email to selenium-...@googlegroups.com.
To unsubscribe from this group, send email to selenium-develo...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/selenium-developers?hl=en.

[Patrick Lightbody]

I agree. Our documentation + website efforts probably need a "reboot" soon... 

I've recently been checking out the Play Framework and I really enjoy their website + docs:

http://www.playframework.org/documentation/1.2.3/home

They have a really nice step-by-step Getting Started guide, which covers installation, IDE configuration, and culminates in a "Hello, World" app.

Then they have a more in-deptch Tutorial that walks you through how to build Yet Another Blogging Engine.

Finally, they have a nice set of documentation, which most closely resembles our docs. I think what we're missing is the equivalent of the Getting Started and Tutorial sections that Play does so well.

Part of the problem, of course, is that Selenium has tried to be "all things to all people". We still suffer from the fact that we have an IDE that even the author doesn't advocate that we use. Our user community is split about 50/50 with people who *love* Selenium IDE and the "Selenese" language and people who are building much more complex test frameworks. The documentation should be VERY different for those two groups.

Patrick

--

Patrick Lightbody

+1 (415) 830-5488

Schedule a meeting with me at http://lightbody.net/schedule

[myndzi]

On Nov 14, 10:06 am, Leo Laskin <llas...@gmail.com> wrote:
> What I hear here is that the "getting started" documentation needs work.  I
> see a lot of complaining, but no fixes.

Now look here. How can you expect me to submit patches or contribute
when I can't even make a simple test case function? I tried to make it
quite clear in my post that it was not a complaint, but it seems I
wasn't clear enough. This is my contribution for now, doing what I can
when I can to try and help make Selenium better. A user, presumably a
contributing user, asked me to post information to this list; while
this is probably not what he had in mind, I think it adequately
conveys my perspective and illustrates where things can be worked on.
In any event, my post didn't deserve this reply. Hopefully this isn't
the prevailing attitude, because I don't waste my time writing
thoughtful commentary for people who don't care.

On Nov 14, 10:12 am, Patrick Lightbody <patr...@lightbody.net> wrote:
> The documentation should be VERY different for those two groups.

A good point. I checked out the Play documentation you linked and it
is indeed quite nice. If that's what you have in mind, I can see why
you might think to split the documentation. While something that
thorough would certainly fall in the category of "excellent", I don't
think nearly so much work need be expended simply to make what is
currently here accessible.

I'm not planning to stay and debate, but I felt a need to respond.
I'll reiterate: I understand what it's like to volunteer your time. I
sympathize with you. I don't have the time, inclination, skill, or
knowledge to contribute significantly by myself, but I do have the
time, skill, and attention to detail to describe what I have done. If
it is not helpful or useful to you, then you needn't bother replying;
I do not expect a reply or action as a result of this posting, it is
only a contribution of sorts, one that is within my ability given in
gratitude for responsive assistance and interest.

[Luke Inman-Semerau]

myndzi, your email / feedback is very welcome. Thank you very much for it. I believe Leo's comments were actually directed more towards Mike than you.

I actually have quite a few take-aways from your email that I'll be trying to work on (I volunteer to help update the docs). There's a lot in there and I only have so much time to work on it myself, so hopefully I'll be able to make it better for the next person who comes across the docs soon.

As for your individual problems, please do come back to the IRC channel and we'll try to help you through them. As for choosing Java over trying Python first, I'm sorry that happened. Just know that python is a fairly well tested language binding and is working quite well in some organizations as their primary testing language. We can help you either way to get started if you choose Java or Python (I happen to use both of those every day).

P.S. that guy who helped you briefly and told you to email here, he created webdriver ;)

 

[Santiago Suarez Ordoñez]

Thanks for the insight, myndzi. All good stuff for sure. Even though it took me a while to read such a long email, it was worth it. Thanks for taking the time to write it.

I see your frustrations and I'm sure all the devs and docs contributors (myself included) are aware of most of these issues.
As Patric explained, I think the main problem with the documentation is how much the project aims for.

Your story was long, but you just outlined the full experience from a single user profile/language/tool (tech savvy/Java/Se2). Now take the documentation efforts from the approach you're outlining and aimed to every person and technology combinations that Selenium could reach. Then is when the real problem can be seen.

Consider writing content for all these specific and detailed step by step guides, from configuring your environment, going through the full API, then detailed and advanced tests, then troubleshooting for all Selenium IDE, Selenium RC, WebDriver and Selenium Grid.
But that's not it, how about all supported programming languages (perl, php, ruby, python, java, C#, javascript). Or all the different Driver implementations (OperaDriver, FirefoxDriver, RemoteDriver, Android, etc). How about aiming for people trying to transition between the main tools, with or without knowledge on languages or Selenium itself, being an advanced user or not even knowing how to code. How about people using TestNG, JUnit, rails, capybara, cucumber, nose, PHPUnit_selenium, LoggingSelenium or any of the existing wrappers, testing frameworks and technologies you could use to write automated tests? You get the idea, the list goes on and on.

Having this humongous sea of content to write, we decided to aim the docs to cover things from a higher level.
As you said, they are good as an overview, poor as a specific step-by-step. This made the docs it a more realistic project at the time we started it and still the full PDF is about 200 pages.

But that doesn't mean that the docs can't be done correctly, they surely can. They just need the time investment that a main tool for market penetration and user entry deserves.
Step one would be to put some good thought and discussion for engineering a clear and focused content structure. One that would cover all the steps a person would have to go, as clearly outlined as possible.
Step two would be several hours of content writing, reviewing and editing.

I think for the first step, we would need a small group of people. Mostly committers who would spend some good time thinking about this problem to later share with everyone a final draft.
Once the main structure of content is outlined and things are clear, a great way to get it done would be to have some kind of docs marathon, where everyone involved in the project takes a specific section of this content gets it over the goal line.

Don't know when the right time for this would be, and whether there's currently bigger fish to fry. But it would be great to keep it in mind, as a project goal. Maybe for the 3.0 release, or maybe we can plan it full a full release week, instead of coding.

Santi

[Mike]

Patrick,

That site does look pretty good. Something like that would help a lot
for newcomers. The Netbeans site has a similar concept, but it is not
as clean as that site either.

When I got started Selenium was in transition from 1.x to 2.x, which
is why I had such a problem initially.

I would like to help, but it would need to be on some part that is
more low priority or had a long lead time, because my schedule is so
full. While I have been a programmer for over 30 years, which is why
I am a strong believer in good documentation ;) , I have been working
on finishing my degree at ITT. That leaves me with very little free
time these days, between work and classes.

If you have something I can work on, feel free to contact me directly
at my ITT E-mail, which I read more often than the cox.net one:
mril...@email.itt-tech.edu

Mike

On Nov 14, 10:12 am, Patrick Lightbody <patr...@lightbody.net> wrote:

> I agree. Our documentation + website efforts probably need a "reboot" soon...
>
> I've recently been checking out the Play Framework and I really enjoy their website + docs:
>
> http://www.playframework.org/documentation/1.2.3/home
>
> They have a really nice step-by-step Getting Started guide, which covers installation, IDE configuration, and culminates in a "Hello, World" app.
>
> Then they have a more in-deptch Tutorial that walks you through how to build Yet Another Blogging Engine.
>
> Finally, they have a nice set of documentation, which most closely resembles our docs. I think what we're missing is the equivalent of the Getting Started and Tutorial sections that Play does so well.
>
> Part of the problem, of course, is that Selenium has tried to be "all things to all people". We still suffer from the fact that we have an IDE that even the author doesn't advocate that we use. Our user community is split about 50/50 with people who *love* Selenium IDE and the "Selenese" language and people who are building much more complex test frameworks. The documentation should be VERY different for those two groups.
>
> Patrick
>
> --
> Patrick Lightbody
> +1 (415) 830-5488

> Schedule a meeting with me athttp://lightbody.net/schedule

> ...
>
> read more »

[myndzi]

A bit of followup from Day 2.

I feel like I stuffed an amazing amount of stuff in my head over that
previous day, and I had relatively little farther to go today. It
turns out that things are pretty easy when you have a good idea what's
going on, but of course I never doubted that.

I went round and round with the design of the Java program until I got
a structure that worked well, and I'm pleased to say that I've
completed my project and it works as expected; I'm now adding many
little details :)

The biggest thing I didn't understand/realize, and I just read back
over the WebDriver parts of the docs page to make sure it wasn't
something I missed, was that *all commands block*. I also didn't
really know how to deal with Exceptions until today. Between learning
those two things, coding got a LOT easier.

I had a problem when I was trying to manipulate two Firefox browsers
which I learned somewhere is an FF bug. I managed to rework the code
so I didn't need to using cookie storage/retrieval, but I was stumped
for a while on why AddCookie froze. Luckily I got results from Google
for that one, telling me I needed to go to the page I wanted to add
the cookie for first. Since the cookie I was working with was a
session/logon cookie, it made sense to load it first - but then things
just went nowhere. Maybe a parameter to specify the domain the cookie
should belong to?

Santiago: I agree, if you look at it that way there is a formidable
amount of work to be done. Hopefully there is some middle ground
between the two extremes :) I have no idea if I'll have the time, but
I may actually understand enough to put together something of a newbie
guide at some point. We'll have to see about that - by succeeding
here, I think I may just have earned myself a lot more work!

Thank you guys for your responsiveness, and keep up the good work.

[Ashlie Stevens]

Greetings,

Last week I went to a meeting to gain an Overview understanding of Selenium and how I might be able to use it where I work. Jim Evans did a fantastic job at telling the history, overview and direction of the product. He also mentioned any volunteers who have interest in writing documentation, as a volunteer, should consider and come forth.  

So here I am, and this post caught my attention since I might have a similar starting point and knowledge base. Currently early stages of self-studying SQL.  I'm taking notes too, to create online how to video tutorials to use where i work to add to our HUGE database of content that is used by large companies that I can't mention here.  This is a project I want to to so it aligns well for the company.  

Also, I do manual software testing; functional, UAT, Beta, Smoke, Regression.  The CEO will be thrilled when I can show him,  vs. just telling him about it, that I have successfully used Selenium to automate severl of our weekly testing functions. So far no one here has stepped up to his automation requests.  He is suggesting something called AutoIT and seems to be stuck on it.  Mostly due to lack of humans and time, perhaps a lack of motivation.  

Once I begin the Selenium journey to learn IDE, and WebArchitecture  I'll want to document it for reference and to share.  What do you all want, and how can I best help now? 

I work for an elearning company with a robust platform that distributes a library of over 100,000 (mostly Msoft) audio and video with companion text content to clients, fast. We also create custom content for companies. So far, I have worked ib several projects doing manual testing of the platform new and existing features.  QA of scripts and videos, and learning the craft of writing scripts on software how to tutorials, from scratch to final user experience. 

For all these reasons I speak of and that I'm continuously learning, would be so cool to learn from your group and help with this project.  I'm resourceful in research, writing and even have a reliable live-in technical resource who uses Selenium, to refer to when needed for help or QA.  

Thanks for your consideration,

Ashlie   

[Dan D]

Hi Ashlie!

> What do you all want, how can I best help now?

The best way to help out, is by submitting Pull Requests (PR) to our repositories!

Whether you use Java or any other language, anytime you find something in the documentation or even code that needs improvement - send a PR!

Considering you're starting to get into this, perhaps a good place to start would also be the documentation site (https://seleniumhq.github.io/docs/site/en/) that we're working on.  :+1:

Good luck!

[Ashlie Stevens]

Hi Dan,

Your feedback is greatly appreciated, and I'll take your advice on a starting point with my own plan to build momentum using Selenium in the coming months.

Thank you!

Ashlie

--

You received this message because you are subscribed to the Google Groups "Selenium Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to selenium-develo...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/75583a11-de72-4b42-a136-942794aa9433%40googlegroups.com.