Style guide for Selenium documentation
Read our contributing documentation for complete instructions on how to add content to this documentation.
Alerts
Alerts have been added to direct potential contributors to where specific help is needed.
When code examples are needed, this code has been added to the site:
{{< alert-code />}}
Which gets displayed like this:
Coding Help
Check our contribution guidelines and code example formats if you’d like to help.
To specify what code is needed, you can pass information inside the tag:
{{< alert-code >}}
specifically code that does this one thing.
{{< /alert-code >}}
Which looks like this:
Coding Help
specifically code that does this one thing.
Check our contribution guidelines and code example formats if you’d like to help.
Similarly, for additional content you can use:
{{< alert-content />}}
or
{{< alert-content >}}
Additional information about what specific content is needed
{{< /alert-content >}}
Which gets displayed like this:
Content Help
Additional information about what specific content is needed
Check our contribution guidelines if you’d like to help.
Capitalization of titles
Our documentation uses Title Capitalization for linkTitle
which should be short
and Sentence capitalization for title
which can be longer and more descriptive.
For example, a linkTitle
of Special Heading might have a title
of
The importance of a special heading in documentation
Line length
When editing the documentation’s source, which is written in plain HTML, limit your line lengths to around 100 characters.
Some of us take this one step further and use what is called semantic linefeeds, which is a technique whereby the HTML source lines, which are not read by the public, are split at ‘natural breaks’ in the prose. In other words, sentences are split at natural breaks between clauses. Instead of fussing with the lines of each paragraph so that they all end near the right margin, linefeeds can be added anywhere that there is a break between ideas.
This can make diffs very easy to read when collaborating through git, but it is not something we enforce contributors to use.
Translations
Selenium now has official translators for each of the supported languages.
- If you add a code example to the
important_documentation.en.md
file, also add it toimportant_documentation.ja.md
,important_documentation.pt-br.md
,important_documentation.zh-cn.md
. - If you make text changes in the English version, just make a Pull Request. The new process is for issues to be created and tagged as needs translation based on changes made in a given PR.
Code examples
All references to code should be language independent, and the code itself should be placed inside code tabs.
Default Code Tabs
The Docsy code tabs look like this:
WebDriver driver = new ChromeDriver();
driver = webdriver.Chrome()
var driver = new ChromeDriver();
driver = Selenium::WebDriver.for :chrome
let driver = await new Builder().forBrowser('chrome').build();
val driver = ChromeDriver()
To generate the above tabs, this is what you need to write.
Note that the tabpane includes langEqualsHeader=true
.
This auto-formats the code in each tab to match the header name.
{{< tabpane langEqualsHeader=true >}}
{{< tab header="Java" >}}
WebDriver driver = new ChromeDriver();
{{< /tab >}}
{{< tab header="Python" >}}
driver = webdriver.Chrome()
{{< /tab >}}
{{< tab header="CSharp" >}}
var driver = new ChromeDriver();
{{< /tab >}}
{{< tab header="Ruby" >}}
driver = Selenium::WebDriver.for :chrome
{{< /tab >}}
{{< tab header="JavaScript" >}}
let driver = await new Builder().forBrowser('chrome').build();
{{< /tab >}}
{{< tab header="Kotlin" >}}
val driver = ChromeDriver()
{{< /tab >}}
{{< /tabpane >}}
Link to GitHub
All code examples should be present and linked to in our example repos.
With the gh-codeblock
shortcode, it is possible to render code hosted in a GitHub
repository. In this case, langEqualsHeader=true
is only needed if the tabpane
mixes
more than one tab
with code hosted on GitHub and code examples added directly in the
markdown file (which should not happen often).
However, disableCodeBlock=true
is needed at the tab
level when using the gh-codeblock
shortcode. This is an example of the gh-codeblock
shortcode usage:
{{< tabpane >}}
{{< tab header="Link" disableCodeBlock=true >}}
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScriptTest.java#L38-L56" >}}
{{< /tab >}}
{{< tab header="No Link" >}}
This content should not get linked to GitHub
{{< /tab >}}
{{< /tabpane >}}
Which looks like this:
@Test
public void eightComponents() {
driver.get("https://duckduckgo.com/");
String title = driver.getTitle();
assertTrue(title.contains("DuckDuckGo"));
driver.manage().timeouts().implicitlyWait(Duration.ofMillis(500));
WebElement searchBox = driver.findElement(By.name("q"));
WebElement searchButton = driver.findElement(By.id("search_button_homepage"));
searchBox.sendKeys("Selenium");
searchButton.click();
searchBox = driver.findElement(By.name("q"));
String value = searchBox.getAttribute("value");
assertEquals("Selenium", value);
}
This content should not get linked to GitHub
Disabling Code Block
If you want your example to include both text and code, you need to disable the default behavior that puts everything inside a code block
Maybe you want something like this:
- Start the driver
WebDriver driver = new ChromeDriver();
- Navigate to a page
driver.get("https://selenium.dev");
- Quit the driver
driver.quit();
For this you need to use disableCodeBlock=true
instead of langEqualsHeader=true
You need to specify which parts are code and which are not yourself now, like this:
{{< tabpane disableCodeBlock=true >}}
{{< tab header="Java" >}}
1. Start the driver
```java
WebDriver driver = new ChromeDriver();
```
2. Navigate to a page
```java
driver.get("https://selenium.dev");
```
3. Quit the driver
```java
driver.quit();
```
{{< /tab >}}
< ... >
{{< /tabpane >}}
Link to GitHub
All code examples should be present and linked to in our example repos.
With the gh-codeblock
shortcode, it is possible to render code hosted in a GitHub
repository. This is an example of the gh-codeblock
shortcode usage:
{{< gh-codeblock path="examples/java/src/test/java/dev/selenium/getting_started/FirstScriptTest.java#L38-L56" >}}
Which looks like this:
@Test
public void eightComponents() {
driver.get("https://duckduckgo.com/");
String title = driver.getTitle();
assertTrue(title.contains("DuckDuckGo"));
driver.manage().timeouts().implicitlyWait(Duration.ofMillis(500));
WebElement searchBox = driver.findElement(By.name("q"));
WebElement searchButton = driver.findElement(By.id("search_button_homepage"));
searchBox.sendKeys("Selenium");
searchButton.click();
searchBox = driver.findElement(By.name("q"));
String value = searchBox.getAttribute("value");
assertEquals("Selenium", value);
}
Code Comments
Minimize code comments because they are difficult to translate. Further, try to avoid over-explaining each line of code unless it is directly related to the page you are writing.