Omit needless words in track tutorial #499

danielmitterdorfer · 2018-05-13T14:52:23Z

No description provided.

dliappis

Thanks for this massive simplification effort!

I left a few comments.

dliappis · 2018-05-13T19:33:47Z

docs/adding_tracks.rst

-* The numbers below the ``documents`` property are needed to verify integrity and provide progress reports. Determine the correct document count with ``wc -l documents.json`` and the size in bytes with ``stat -f "%z" documents.json``.
-* You can add as many queries as you want. We use the `official Python Elasticsearch client <http://elasticsearch-py.readthedocs.org/>`_ to issue queries.
-
+The numbers below the ``documents`` property are needed to verify integrity and provide progress reports. Determine the correct document count with ``wc -l documents.json`` and the size in bytes with ``stat -f "%z" documents.json``.


I think "below" could be replaced by "under" as my first instinct is to look at the next line/property.

dliappis · 2018-05-13T19:39:47Z

docs/adding_tracks.rst

-
-* Iteration-based tasks will run at most one warmup iteration and one measurement iteration.
-* Time-period-based tasks will run for at most 10 seconds without any warmup.
+You can check your track very quickly for syntax errors when you invoke Rally with ``--test-mode``. Rally postprocesses its internal track representation then:


then at the end of the sentence sounds weird to me. How about:

Rally now postprocesses its internal track representation:

How about this?

Rally postprocesses its internal track representation as follows:

Sounds good.

dliappis · 2018-05-13T19:42:37Z

docs/adding_tracks.rst


-Rally will postprocess all data file names of a track. So instead of ``documents.json``, Rally will attempt to find ``documents-1k.json`` and will assume it contains 1.000 documents. However, you need to prepare these data files otherwise this test mode is not supported.
+* Iteration-based tasks run at most one warmup iteration and one measurement iteration.
+* Time-period-based tasks run for at most 10 seconds without warmup.


run for at most --> run, at most, for

I interpret the "at most" as a restrictive clause in this case. Hence we should not enclose it in commas. So I'd write: "run at most for".

dliappis · 2018-05-13T19:49:52Z

docs/adding_tracks.rst

@@ -409,7 +403,7 @@ If you want to reuse operation definitions across challenges, you can also defin

 Note how we reference to the operations by their name (e.g. ``create``, ``bulk-index``, ``force-merge`` or ``query-match-all``).

-If your track consists of multiple challenges, it can be cumbersome to include them all explicitly. Therefore Rally brings a ``collect`` helper that collects all related files for you. Let's adapt our track to use it::
+It can be cumbersome to include multiple challenges explicitly so you can use Rally's ``collect`` helper instead::


Sounds a little strange (to me). What about:

You can also use Rally's collect helper to simplify including multiple challenges explicitly:

dliappis · 2018-05-13T19:55:40Z

docs/adding_tracks.rst


 .. note::

    Rally's log file contains the fully rendered track after it has loaded it successfully.

 .. note::

-    If you define multiple challenges, Rally will run the challenge where ``default`` is set to ``true``. If you want to run a different challenge, provide the command line option ``--challenge=YOUR_CHALLENGE_NAME``.
+    If you define multiple challenges, Rally runs the challenge where ``default`` is set to ``true``. If you want to run a different challenge, provide the command line option ``--challenge=YOUR_CHALLENGE_NAME``.

 You can even use `Jinja2 variables <http://jinja.pocoo.org/docs/2.9/templates/#assignments>`_ but you need to import the Rally helpers a bit differently then. You also need to declare all variables before the ``import`` statement::


Not affected by this PR, but now that I saw it, should we re-order then like:

but then you need to import the Rally helpers a bit differently.

Makes sense. I've changed it.

dliappis · 2018-05-13T20:03:10Z

docs/adding_tracks.rst


 Advanced topics
 ---------------

 Template Language
 ^^^^^^^^^^^^^^^^^

-Rally uses `Jinja2 <http://jinja.pocoo.org/docs/dev/>`_ as template language. This allows you to use Jinja2 expressions in track files.
+Rally uses `Jinja2 <http://jinja.pocoo.org/docs/dev/>`_ as template language so you can use Jinja2 expressions in track files.


 Extension Points
 """"""""""""""""

 Rally also provides a few extension points to Jinja2:


How about just a few extensions (without points)?

That's simpler indeed. I also changed the heading accordingly.

dliappis · 2018-05-13T20:07:43Z

docs/adding_tracks.rst

@@ -568,7 +565,7 @@ You can find an example in the http_logs track::
      }
    }

-The data set that is used in the http_logs track starts on 26-04-1998 but we want to ignore the first few days for this query, so we start on 15-05-1998. The expression ``{{'15-05-1998' | days_ago(now)}}`` yields the difference in days between now and the fixed start date and allows us to benchmark time range queries relative to now with a predetermined data set.
+The data set that is used in the ``http_logs`` track starts on 26-04-1998 but we want to ignore the first few days for this query, so we start on 15-05-1998. The expression ``{{'15-05-1998' | days_ago(now)}}`` yields the difference in days between now and the fixed start date and allows us to benchmark time range queries relative to now with a predetermined data set.


Substitute yields with just provides (or returns)? Not every track author may be familiar with Python's yield and generators.

I use the word "yield" here in a mathematical, not in a software engineering context.

dliappis · 2018-05-13T20:10:50Z

docs/adding_tracks.rst

@@ -605,7 +602,7 @@ First, define the name of your parameter source in the operation definition::
      "professions": ["mechanic", "physician", "nurse"]
    }

-Rally will recognize the parameter source and looks then for a file ``track.py`` in the same directory as the corresponding JSON file. This file contains the implementation of the parameter source::
+Rally recognizes the parameter source and looks for a file ``track.py`` next to ``track.json``. This file contains the implementation of the parameter source::


Replace next with:

in the same directory (or folder) as track.json.

I think "next to" is just as clear?

dliappis · 2018-05-13T20:22:05Z

docs/adding_tracks.rst

@@ -786,11 +775,11 @@ Then create a file ``track.py`` next to ``track.json`` and implement the followi
 The function ``percolate`` is the actual runner and takes the following parameters:

 * ``es``, which is the Elasticsearch Python client


I think which can be skipped

Makes sense. I've changed it.

dliappis · 2018-05-13T20:22:30Z

docs/adding_tracks.rst

@@ -786,11 +775,11 @@ Then create a file ``track.py`` next to ``track.json`` and implement the followi
 The function ``percolate`` is the actual runner and takes the following parameters:

 * ``es``, which is the Elasticsearch Python client
-* ``params`` which is a dict of parameters provided by its corresponding parameter source. Treat this parameter as read only and do not attempt to write to it.
+* ``params`` which is a ``dict`` of parameters provided by its corresponding parameter source. Treat this parameter as read-only.


Again which I think is not needed.

Makes sense. I've changed it.

dliappis · 2018-05-14T06:17:20Z

Thanks for iterating, LGTM.

Omit needless words in track tutorial

f0e9db8

danielmitterdorfer added enhancement Improves the status quo :Docs Changes to the documentation labels May 13, 2018

danielmitterdorfer added this to the 0.12.0 milestone May 13, 2018

danielmitterdorfer requested a review from dliappis May 13, 2018 14:52

Add missing backtick

daea5e6

dliappis reviewed May 13, 2018

View reviewed changes

Review comments

b0ec10b

danielmitterdorfer merged commit fee77eb into elastic:master May 14, 2018

danielmitterdorfer deleted the short-track-tutorial branch May 14, 2018 07:11

danielmitterdorfer modified the milestones: 0.12.0, 1.0.0 May 25, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Omit needless words in track tutorial #499

Omit needless words in track tutorial #499

danielmitterdorfer commented May 13, 2018

dliappis left a comment

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018 •

edited

Loading

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018 •

edited

Loading

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis May 13, 2018

danielmitterdorfer May 14, 2018

dliappis commented May 14, 2018

		@@ -786,11 +775,11 @@ Then create a file ``track.py`` next to ``track.json`` and implement the followi
		The function ``percolate`` is the actual runner and takes the following parameters:

		* ``es``, which is the Elasticsearch Python client

Omit needless words in track tutorial #499

Omit needless words in track tutorial #499

Conversation

danielmitterdorfer commented May 13, 2018

dliappis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielmitterdorfer May 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielmitterdorfer May 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dliappis commented May 14, 2018

danielmitterdorfer May 14, 2018 •

edited

Loading

danielmitterdorfer May 14, 2018 •

edited

Loading