Documentation revisions

[lukeis]

Originally reported on Google Code with ID 1926

Selenium - Documentation (Offline PDF)

Editorial feedback:
In general, page breaks in the PDF aren't great, often splitting images from text,
titles from text, etc.
p.6 "it's" should be "its": While Selenium was a tremendous tool, it wasn’t without
it’s drawbacks.
p.7 thing should be plural: At the time of writing there is no plan to add such thing.
p.9 misspelled strength: This is perhaps Selenium’s greatest strenght when compared
with other automation tools.
p.9 inconsistently refers to Selenium 1, Selenium RC, Sel-R --> Are these the same
thing?
p.9 varies should be singular: how to implement data-driven tests (tests where one
can varies the data between test passes)
p.11,13,14 Screenshot is too large to fit on this page and ends up on the next, leaving
a large expanse of whitespace
p.16 The screenshot doesn't match what I have seen in my Firefox IDE plugin. (WHAT
VERSION DO I HAVE?)
(next screenshot matches but is not explained)
p.19 This reads strangely. Maybe say "in purple text"? : Your comment will appear in
purple font.
p.20 WYSIWYG isn't defined. Maybe the readers know enough to do without a definition?
Or is this meant to accomodate complete beginners?
p.21 This should be a comma-separated list (i.e. ", and"): three “flavors”: Actions,
Accessors and Assertions.
p.25 The line numbers of the HTML code do not match the answers below (e.g. line 4
does not contain the word "password" but the text claims identifier=password returns
line 4)
p.37 lines of HTML run off the right side of the page, so they should wrap around.
Because the HTML that ran off the right side of the PDF page wasn't avalable, I could
use the last 2 buttons described in the example.
p.37 Since you don't use the line numbers for the HTML page, remove them so that it's
easy to copy the HTML and open it in a browser. The page break also makes copying the
HTML harder. None of the buttons worked for me in Firefox 3.6.17 on an offline computer.
I also tried the online page for easier copying, saved the HTML to a local file, opened
it in Firefox3.6 and then tried opening it in IE8. Neither browser handled the open
named or nameless windows.
p.37 "Foo" is used without context. Is this meant to accomodate complete beginners?
p.37 Typo! This should say "alerts" not "asserts": Let’s start with asserts because
they are the simplest pop-up to handle.
p.38 Target should say "Choose an option." not "Choose and option."
p.38 You may want to find a different example for Confirmations. Selenium IDE 1.0.11
in Firefox 4.0.1 records the chooseCancelOnNextConfirmation before the click and playback
in this order does not cause any errors! If I do as the text suggests and change the
order, then I get the error it mentions.
p.39 Running Selenium IDE 1.0.11 in Firefox 4.0.1, I do not see any page elements highlighted
when using the Find button on the example pop-up HTML page.
p.41 The colocation bug mentioned here appears to be resolved in Selenium IDE 1.0.11
Known Bug? Cannot widen the export language pane on Selenium IDE Options < Formats
tab.
Known Bug? Selenium IDE Options < Formats tab: Selecting a language with enough UI
components to fill the right-hand side of the current window (e.g. Perl) pushes the
action buttons off the screen.
p.42 Change "i.e. Java, PHP" to "(e.g. Java, PHP)"
p.42 Change "File=>Save" to "File=>Export Test Case As..." and you may want to revise
the description since Selenium IDE 1.0.11 prompts for language selection at this point
p.42 Change "Options=>Options=>Format tab." to Options=>Options=>Formats tab." (plural
in the name)
p.42 Chapter name is now "Selenium 1 (Selenium RC)" rather than "Selenium-RC"
p.45 Reword this "a tool for automating testing web applications," to be "a tool for
automating web applications testing,"
p.45 Reword this "which will help make" to "which will help to make"
p.46 The text mentions a next example and then there isn't one. Has it already been
written but not included? Should there be some placeholder information here?
p.48 Documentation bug? Clicking the link for Web Element results in a 404 error!
p.48 Unnecessary passive voice. Change "an exception will be thrown." to "WebDriver
throws an exception."
p.49 Code sample runs off the right-hand side of the page
p.50 Typos "triggerd and action" should be "triggered an action"
p.51 Code sample runs off the right-hand side of the page
[Note: Did not read pages 52 to 64]
p.69 Put Sample Test Script table on a separate line. Currently the text wraps around
it.
p.69 The Google search example doesn't seem to work for me with Selenium IDE 1.0.11
on 6/19/11
p.70 Code sample runs off the right-hand side of the page
p.72 Code sample runs off the right-hand side of the page
p.77 update #2 for Ruby scripts is strangely spaced on the page, not lined up like
update #1
p.79 Code sample runs off the right-hand side of the page
p.80 Code sample runs off the right-hand side of the page
p.81 I think you mean "begin with the framework's built-in reporting features" not
"being with the framework’s built-in reporting features"
p.84 replace "first validate if the element is really present" with "first validate
whether the element is really present"
p.84 Code sample runs off the right-hand side of the page
p.85 Code sample runs off the right-hand side of the page
p.88 grammar error. use "its filename and directory path" instead of "it’s filename
and directory path"
p.88 Code sample runs off the right-hand side of the page
[Note: Did not read pages 89 to 93]
p.94 Code sample runs off the right-hand side of the page
[Note: Did not read pages 94 to 100]
p.101 remove this comma "useful to both, those new"
p.102 typo: should say "infrequently changed then manual testing may" not "infrequently
changed then manual tseting may"
p.102 typo: should say "typically mirror the user-scenarios" not "typically mirro the
user-scenarios"
p.102 typo and sounds awkward. I would rewrite this: "This means your test script which
is verify that a document exists may not have a consistent identifier to user for locating
that document." to "A test script verifying that a document exists may not have a consistent
identifier to use for locating that document."
p.102 What? "Thing though certainly depends on the function of the web application."
Did you mean "This though ..."?
p.104 grammar error. use "its XPath processor" rather than "it’s XPath processor"
p.104 typo: should be "This technique is specific to links though." not "This technique
is speciic to links though."
p.104 grammar error. use "a page element whose identifer" rather than "a page element
who’s identifer"
p.105 missing the closing quotes in this code: selenium.click("addForm:_ID74:_ID75:0:_ID79:0:checkBox);
p.106 Code sample runs off the right-hand side of the page
p.107 Capitalize Selenium in "common usage of wrapping selenium methods"
p.107 Code samples run off the right-hand side of the page
p.108 change "Its primary purpose for making test script management much easier." to
"Its primary purpose is making test script management much easier."
p.110 Not sure what this should say: "The id-locators would would be spread in multiple
tests"
p.110 Code samples run off the right-hand side of the page
p.111 Code samples run off the right-hand side of the page
p.113 Code samples run off the right-hand side of the page
p.117 Unnecessary passive voice: "It can be quite simple to extend Selenium, adding
your own actions, assertions and locator-strategies. This is done with JavaScript by
adding methods to the Selenium object prototype, and the PageBot object prototype."
[try instead] "Extending Selenium by adding your own actions, assertions and locator-strategies
can be quite simple. Add JavaScript methods to the Selenium object prototype and the
PageBot object prototype."
p.118 The section title for 9.3.1 is long and missing a comma in the comma-separated
list: "Automatic availability of storeFoo, assertFoo, assertNotFoo, waitForFoo and
waitForNotFoo for every getFoo" Maybe this would be better? "Prototype generates additional
commands" (rather than a list, which then doesn't match the list in the first line
of the following paragraph.)
p.118 Why is "store-Foo" hypenated for a line break when other lines in the same paragraph
are not nicely broken up? Seems unnecessary: "All getFoo and isFoo methods on the Selenium
prototype automatically result in the availability of store-Foo, assertFoo, assertNotFoo,
verifyFoo, verifyNotFoo, waitForFoo, and waitForNotFoo commands."
p.119 Code samples run off the right-hand side of the page
p.119 Revise "need to make a couple small edits" to need to make a couple of small
edits"
p.119-120 9.6.1 Example: The numbering here should probaby be sequential from one paragraph
to the next, unless you are actually starting over with a new set of instructions after
the first code snippet.
p.120 Typo: "pass in your user-extensinos.js file." should be "pass in your user-extensions.js
file."
p.120 Code samples run off the right-hand side of the page
[Note: Did not read pages 123 to 158]
p.159 Separate these two sentences: "In order to locate an element based on associated
class in XPath you must consider that the element could have multiple classes and defined
in any order, however with CSS locators this is much simpler (and faster)." [like so]
"In order to locate an element based on associated class in XPath you must consider
that the element could have multiple classes and defined in any order. However, with
CSS locators, this is much simpler
 (and faster)." [or you can use a semicolon] "In order to locate an element based on
associated class in XPath you must consider that the element could have multiple classes
and defined in any order; however, with CSS locators, this is much simpler (and faster)."

Reported by aclairefication on 2011-06-25 14:29:26

[lukeis]

Reported by david.burns@theautomatedtester.co.uk on 2011-06-26 05:04:16

[lukeis]

Reported by luke.semerau on 2011-07-19 22:40:27

• Labels added: Component-Docs

[lukeis]

p.37 Thats should read as That's: Under section 3.22.1 Alerts, the sentence:
You may be thinking "Thats odd, I never tried to assert that alert."
should read as:
You may be thinking "That's odd, I never tried to assert that alert."

Reported by pankaj.nith on 2011-09-10 22:09:13

[lukeis]

p.54 Under Section 4.7.5 Moving Between Windows and Frames, the use of "any frames"
in the sentence "Some web applications have any frames or multiple windows." seems
inappropriate.

Reported by pankaj.nith on 2011-09-10 23:00:51

[lukeis]

Assigning it to me to work on it

Reported by tkumarb on 2011-11-10 12:33:28

[lukeis]

This issue was updated by revision r14841.

Fixed issues from 6 to 25. Notice that fix does not take care of spacing issues with
pages

Reported by tkumarb on 2011-11-21 18:16:17

[lukeis]

This issue was updated by revision r15215.

Fixed issues from 25 onwards. Regarding code block getting chopped in pdf, I would
take it off line with doc team

Reported by tkumarb on 2011-12-17 18:54:25

[lukeis]

last time I went to try and get a PDF I had forgotten how to do this.  There was no
obvious link or anything that I could see.  Can someone tell me how we do this?

Reported by pgrandje on 2011-12-17 21:26:27

[lukeis]

pdf link is available under footer section "Documentation" of site http://seleniumhq.org/docs/

Reported by tkumarb on 2011-12-18 03:11:22

[lukeis]

Just assigned this ticket to myself. I'll see what I can do with the other issues.

Thanks for reporting!

Reported by santiycr on 2011-12-21 23:27:56

• Status changed: Accepted

[lukeis]

I've removed the link to the offline documentation and stopped building it for sehq
(I did this a while ago).

A few reasons I did this were it was quite painful to figure out how to fix certain
issues and also bugs like this where it's not very easy to map the issue reported by
the user who references the pdf location and the actual code location in the chapters.

I've left instructions on how to build the pdf for anyone to do themselves here:
http://code.google.com/p/selenium/issues/detail?id=4959#c3

I'll likely add that to a wiki page and the docs themselves at some point.

Marking this bug as fixed as Tarun seems to have taken care of most of it.

Reported by luke.semerau on 2013-01-06 18:24:07

• Status changed: Fixed

[lukeis]

Reported by luke.semerau on 2015-09-17 18:13:04

• Labels added: Restrict-AddIssueComment-Commit