update docs for consistency

closes #50

Author: Gerit Wagner

CITATION.cff

@@ -1,5 +1,5 @@
 cff-version: 0.1.0
-message: "If you use this software, please cite it as below."
+message: "Please cite this software as below."
 authors:
 - family-names: "Eckhardt"
   given-names: "Peter"

CONTRIBUTING.md

@@ -1,26 +1,26 @@
 ## How to contribute
 
-Thank you for your interest in contributing to the *search-query* package!
-We encourage you to have a look at our [open issues](https://github.com/CoLRev-Environment/search-query/issues) or open a new one if you encounter an un-addressed problem.
+Contributions to the *search-query* package are welcome.
+The [open issues](https://github.com/CoLRev-Environment/search-query/issues) highlight outstanding problems and potential enhancements.
 
-Here are some guidelines for how to contribute to the package.
+The following guidelines describe how to contribute to the package.
 
 **Want to implement a new search platform?**
 
-Right now, the package supports a limited amount of search platforms.
-We therefore appreciate help in expanding the package with new platforms.
-If you’re unsure which platform to implement, check our [platform roadmap](https://github.com/CoLRev-Environment/search-query/issues/46).
+Right now, the package supports a limited number of search platforms.
+Help in expanding the package with new platforms is appreciated.
+The [platform roadmap](https://github.com/CoLRev-Environment/search-query/issues/46) indicates priority areas.
 
-Our [development documentation](https://colrev-environment.github.io/search-query/dev_docs/overview.html) includes an overview of best practices for implementing a new search platform, along with code skeletons to help you get started.
+The [development documentation](https://colrev-environment.github.io/search-query/dev_docs/overview.html) provides an overview of best practices for implementing a new search platform, along with code skeletons.
 
 **Found a bug?**
 
-If you found a bug or encountered any issues while using the package, you can contribute by [opening an issue](https://github.com/CoLRev-Environment/search-query/issues/new).
-When possible, include a minimal code example and describe the expected behavior.
+Bug reports and other issues can be submitted via [the issue tracker](https://github.com/CoLRev-Environment/search-query/issues/new).
+A minimal code example and a description of expected behavior facilitate triage.
 
 **Running and extending the test suite**
 
-We use [`pytest`](https://docs.pytest.org/) for testing.
+[`pytest`](https://docs.pytest.org/) is used for testing.
 Tests are located in the `tests/` directory and are organized by functionality (e.g., linting, parsing, platform-specific implementations).
 
 To run all tests locally:
@@ -52,15 +52,14 @@ Adding new tests
 * Group related tests into logical classes or functions.
 * Use clear and descriptive test names (`test_what_it_does`).
 * Prefer [pytest parameterization](https://docs.pytest.org/en/stable/how-to/parametrize.html) when testing multiple input–output pairs.
-* If you implement a new search platform, include tests for end-to-end search-query functionality
+* Implementing a new search platform should include tests for end-to-end search-query functionality.
 
 **Other ways to contribute**
 
-Of course, we also welcome smaller contributions, such as bug fixes or improvements to the package documentation.
+Smaller contributions, such as bug fixes or improvements to the package documentation, are also appreciated.
 <!-- TODO: Include guide for contributing to docs? -->
 
-If you’ve made changes to the source code or documentation, fork the repository and open a [pull request](https://github.com/CoLRev-Environment/search-query/compare).
-Please include a clear description of your changes.
+After making changes to the source code or documentation, fork the repository and open a [pull request](https://github.com/CoLRev-Environment/search-query/compare) with a clear description of the changes.
 
 ### Adding a new parser/serializer version
 

README.md

@@ -39,14 +39,14 @@ digital_synonyms = OrQuery(["digital", "virtual", "online"], field="abstract")
 work_synonyms = OrQuery(["work", "labor", "service"], field="abstract")
 query = AndQuery([digital_synonyms, work_synonyms])
 ```
-We can also parse a query from a string or a JSON search file (see the [overview of platform identifiers](https://colrev-environment.github.io/search-query/platforms/platform_index.html))
+A query can also be parsed from a string or a JSON search file (see the [overview of platform identifiers](https://colrev-environment.github.io/search-query/platforms/platform_index.html))
 ```python
 from search_query.parser import parse
 
 query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
 query = parse(query_string, platform="pubmed")
 ```
-A useful feature of parsers is the built-in **linter** functionality, which helps us to validate the query by identifying syntactical errors:
+The built-in **linter** functionality validates queries by identifying syntactical errors:
 ```python
 from search_query.parser import parse
 
@@ -58,8 +58,8 @@ query = parse(query_string, platform="pubmed")
 #   Query: ("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]
 #                                                ^^^
 ```
-Once we have created a `query` object, we can translate it for different databases.
-Note how the syntax is translated and how the search for `Title/Abstract` is split into two elements:
+Once a `query` object is created, it can be translated for different databases.
+The translation illustrates how the search for `Title/Abstract` is split into two elements:
 ```python
 from search_query.parser import parse
 
@@ -96,7 +96,7 @@ A Jupyter Notebook demo (hosted on Binder) is available here:
 
 ## Encounter a problem?
 
-If you find a bug or run into any issues while using the package, please [open an issue](https://github.com/CoLRev-Environment/search-query/issues) or contact one of the developers.
+Bug reports or issues can be submitted via [the issue tracker](https://github.com/CoLRev-Environment/search-query/issues) or by contacting the developers.
 
 ## How to cite
 
@@ -110,9 +110,9 @@ The package was developed as part of Bachelor's theses:
 - Eckhardt, P. (2025). Advances in literature searches: Evaluation, analysis, and improvement of Web of Science queries. Otto-Friedrich-University of Bamberg.
 - Ernst, K. (2024). Towards more efficient literature search: Design of an open source query translator. Otto-Friedrich-University of Bamberg.
 
-## Not what you are looking for?
+## Alternative tools
 
-This Python package was developed with the purpose of integrating it into other literature management tools. If that isn't your use case, it might be useful for you to look at these related tools:
+This Python package is designed for programmatic and CLI-based use, as well as for integration into other literature management tools. For different scenarios, the following related tools may be helpful:
 
 - [LitSonar](https://litsonar.com/)
 - [Polyglot](https://sr-accelerator.com/#/polyglot)

docs/Makefile

@@ -1,8 +1,7 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
+# These variables can be set from the command line or from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source

docs/make.bat

@@ -13,12 +13,11 @@ set BUILDDIR=build
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
+        echo.The 'sphinx-build' command was not found. Ensure Sphinx is installed,
+        echo.then set the SPHINXBUILD environment variable to point
+        echo.to the full path of the 'sphinx-build' executable or add the Sphinx directory to PATH.
+        echo.
+        echo.If Sphinx is not installed, it can be obtained from
 	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )

docs/source/dev_docs/linter_development.rst

@@ -19,7 +19,7 @@ Each linter must override the `validate_tokens()` method and the `validate_query
 Best Practices
 --------------
 - **Use standardized linter messages** defined in `constants.QueryErrorCode`.
-- **Add details** in messages for user guidance (e.g., invalid format, missing logic).
+- **Add details** in messages for guidance (e.g., invalid format, missing logic).
 - Ensure **valid token sequences** using the `VALID_TOKEN_SEQUENCES` dictionary.
 - Consider using **utility methods** provided by `linter_base.py`:
   - `check_unbalanced_parentheses()`
@@ -46,7 +46,7 @@ such patterns, for example:
 
    LINT_2001: Operator "SAME" is deprecated. Use NEAR/0.
 
-These messages surface to users during parsing and encourage upgrades.
+These messages appear during parsing and encourage upgrades.
 
 .. literalinclude:: linter_skeleton.py
    :language: python

docs/source/dev_docs/overview.rst

@@ -35,7 +35,7 @@ Versioned implementations live inside
 To add a new parser or serializer version:
 
 1. copy the latest versioned directory (e.g. ``v1`` → ``v2``),
-2. apply your changes,
+2. apply the changes,
 3. register the new version in ``search_query.parser.PARSERS``,
    ``search_query.serializers.SERIALIZERS`` or
    ``search_query.translators.TRANSLATORS`` so it becomes discoverable.

docs/source/dev_docs/translator_development.rst

@@ -38,7 +38,7 @@ update the implementation as needed, and register the new version in the ``TRANS
 Utility Methods Provided
 ------------------------
 
-From the base class (`QueryTranslator`), you can use:
+The base class (`QueryTranslator`) provides the following utilities:
 
 - ``move_field_from_operator_to_terms(query)``:
   Moves a shared search field from the operator level to each child query.

docs/source/index.rst

@@ -47,7 +47,7 @@ Creating a query programmatically is simple:
     work_synonyms = OrQuery(["work", "labor", "service"], field="abstract")
     query = AndQuery([digital_synonyms, work_synonyms])
 
-We can also parse a query from a string or a `JSON search file <#json-search-files>`_ (see the :doc:`overview of platform identifiers </platforms/platform_index>`):
+A query can also be parsed from a string or a `JSON search file <#json-search-files>`_ (see the :doc:`overview of platform identifiers </platforms/platform_index>`):
 
 .. code-block:: python
 
@@ -57,7 +57,7 @@ We can also parse a query from a string or a `JSON search file <#json-search-fil
     query = parse(query_string, platform="pubmed")
 
 
-A useful feature of parsers is the built-in **linter** functionality, which helps us to validate the query by identifying syntactical errors:
+The built-in **linter** functionality validates queries by identifying syntactical errors:
 
 .. code-block:: python
 
@@ -71,8 +71,8 @@ A useful feature of parsers is the built-in **linter** functionality, which help
     #   Query: ("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]
     #                                                ^^^
 
-Once we have created a :literal:`query` object, we can translate it for different databases.
-Note how the syntax is translated and how the search for :literal:`Title/Abstract` is split into two elements:
+Once a :literal:`query` object is created, it can be translated for different databases.
+The translation illustrates how the search for :literal:`Title/Abstract` is split into two elements:
 
 .. code-block:: python
    :linenos:
@@ -116,7 +116,7 @@ A Jupyter Notebook demo (hosted on Binder) is available here:
 Functional Overview
 =======================
 
-The search-query package is built to support researchers throughout the entire lifecycle of academic search query management.
+The search-query package supports the entire lifecycle of academic search query management.
 Below is a high-level overview of the core functionalities:
 
 .. image:: presentation.png

docs/source/lint/FIELD_0003.rst

@@ -23,6 +23,6 @@ FIELD_0003 — field-extracted
 
 **Typical fix**: Explicitly specify the search fields in the query string rather than relying on a general search field setting. (EBSCO)
 
-**Rationale**: Researchers may copy the search_string and miss the general_field, incorrectly reproducing the query.
+**Rationale**: The search_string may be copied and the general_field omitted, leading to incorrect reproduction of the query.
 
 **Back to**: :ref:`lint`