Rewrite this to make it clear the roles and profiles pattern would be

the better idea.

diff --git a/README.markdown b/README.markdown
index 827ef6fa66faf925869396dcc3611c7e9fc29d53..bca71c08f0d44daf995a11616909ebee8d2ce2ae 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -197,24 +197,56 @@ Drop all:
 
 ###Application-specific rules
 
-Application-specific rules can live anywhere you declare the firewall resource. It is best to put your firewall rules close to the service that needs it, such as in the module that configures it.
-
-You should be able to add firewall rules to your application-specific classes so firewalling is performed at the same time when the class is invoked.
-
-For example, if you have an Apache module, you could declare the class as below
-
-    class apache {
-      firewall { '100 allow http and https access':
-        port   => [80, 443],
-        proto  => tcp,
-        action => accept,
-      }
-      # ... the rest of your code ...
-    }
-
-When someone uses the class, firewalling is provided automatically.
-
-    class { 'apache': }
+Puppet doesn't care where you define rules, and this means that you can place
+your firewall resources as close to the applications and services that you
+manage as you wish.  If you use the [roles and profiles
+pattern](https://puppetlabs.com/learn/roles-profiles-introduction) then it
+would make sense to create your firewall rules in the profiles, so that they
+remain close to the services managed by the profile.
+
+An example of this might be:
+
+```puppet
+class profile::apache {
+  include apache
+  apache::vhost { 'mysite': ensure => present }
+
+  firewall { '100 allow http and https access':
+    port   => [80, 443],
+    proto  => tcp,
+    action => accept,
+  }
+}
+```
+
+
+However, if you're not using that pattern then you can place them directly into
+the individual module that manages a service, such as:
+
+```puppet
+class apache {
+  firewall { '100 allow http and https access':
+    port   => [80, 443],
+    proto  => tcp,
+    action => accept,
+  }
+  # ... the rest of your code ...
+}
+```
+
+This means if someone includes either the profile:
+
+```puppet
+include profile::apache
+```
+
+Or the module, if you're not using roles and profiles:
+
+```puppet
+  include ::apache
+```
+
+Then they would automatically get appropriate firewall rules.
 
 ###Other rules