diff --git a/rules/S2734/python/rule.adoc b/rules/S2734/python/rule.adoc
index d6d5b168d4..186eaa34fe 100644
--- a/rules/S2734/python/rule.adoc
+++ b/rules/S2734/python/rule.adoc
@@ -1,31 +1,41 @@
+This rule raises an issue when the ``++__init__++`` method of a class contains a `return` or a `yield` statement.
+
 == Why is this an issue?
 
-By contract, every Python function returns something, even if it's the ``++None++`` value, which can be returned implicitly by omitting the ``++return++`` statement, or explicitly. 
+By contract, every Python function returns something, even if it is the ``++None++`` value, which can be returned implicitly by omitting the ``++return++`` statement, or explicitly. 
 
 
-The ``++__init__++`` method is required to return ``++None++``. A ``++TypeError++`` will be raised if the ``++__init__++`` method either ``++yield++``s or ``++return++``s any expression other than ``++None++``. Returning some expression that evaluates to ``++None++`` will not raise an error, but is considered bad practice.
+The ``++__init__++`` method is required to return ``++None++``. A ``++TypeError++`` will be raised if the ``++__init__++`` method either yields or returns any expression other than ``++None++``. While explicitly returning an expression that evaluates to ``++None++`` will not raise an error, it is considered bad practice.
 
+To fix this issue, make sure that the ``++__init__++`` method does not contain any return statement.
 
-=== Noncompliant code example
+=== Code examples
 
-[source,python]
+==== Noncompliant code example
+
+[source,python,diff-id=1,diff-type=noncompliant]
 ----
 class MyClass(object):
     def __init__(self):
         self.message = 'Hello'
-        return self  # Noncompliant
+        return self  # Noncompliant: a TypeError will be raised
 ----
 
 
-=== Compliant solution
+==== Compliant solution
 
-[source,python]
+[source,python,diff-id=1,diff-type=compliant]
 ----
 class MyClass(object):
     def __init__(self):
         self.message = 'Hello'
 ----
 
+== Resources
+
+=== Documentation
+
+* https://docs.python.org/3/reference/datamodel.html#object.++__init__++[The ``++__init__++`` method]
 
 
 ifdef::env-github,rspecator-view[]