A brief analysis of BrowserStack's documentation

Based on my 30 minute analysis of BrowserStack’s documentation and comparing with a competitor’s documentation, I don’t find anything that I strongly dislike. However, as a technical writer trained to pay attention to details, I have the following nitpicks:

Principles of minimalism are not followed

For example, in Getting started - Python - Prerequisites, the first bullet point is verbose.

Existing sentence:

You need to have BrowserStack Username and Access key, which you can find in
your account settings. If you have not created an account yet, you can sign up
for a Free Trial or purchase a plan.

Suggested sentence:

Note your BrowserStack Username and Access key from the account settings.
Unregistered users can sign up for a trial account or purchase a plan.

The suggestion also demonstrates restructuring of sentences to emphasize user’s actions, and brings more clarity.

Section headings are not in gerund form

For example, in Getting started - Python - Run your first test:

Existing heading:

Run your first test

Suggested heading:

Running your first test

Gerund forms of phrases are appropriate for highlighting a process, which might contain several steps. For the steps, we can use action oriented sentences in simple present tense, such as “Create a sample test code file”.

Admonitions are misused

For example:

The following Warning should ideally be a Caution, because the user needs to be mindful about adding the driver.quit() statement at the end of the code.

Warning admonition example
Protip is not a standard admonition. Instead, use Tip.

Protip admonition example

Some unnecessary images

Images could have been used more sparingly to avoid maintenance problems. This is even more important for images that represent products such as GitHub, which are beyond BrowserStack’s control.

In addition, images without appropriate alt-text hampers accessibility and SEO.

Doc site UI/UX can be improved

Modern documentation websites adopt a three-column approach: documentation suite navigation on the left, content in the middle, and current page ToC on the right. BrowserStack’s documentation website mostly leaves the right column blank. As a result, the left navigation panel looks more crowded and needs frequent scrolling.

General comment

Some navigation links within the text/content are broken, especially the ones that navigates to different sections within the same article.
In lots of occasions, the writing style deviates significantly from Google’s documentation style guide. In fact, a seasoned writer can easily identify the documents contributed by developers, testers, product managers, or customer support. While this is not a big problem, the documentation experience can certainly be made more consistent.

Bonus

Modern test environments, especially in enterprise situations, are mostly containers running on clusters. If the onboarding docs describe procedures using containers, the onboarding experience and the documentation becomes more standardized and maintainable.

A brief analysis of BrowserStack’s documentation