Some rewording recommended by @phadej

snoyberg · snoyberg · commit b046f098c4cb · 2018-01-16T12:14:13.000+02:00
diff --git a/doc/stack_yaml_vs_cabal_package_file.md b/doc/stack_yaml_vs_cabal_package_file.md
@@ -1,21 +1,22 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://rawgit.com/commercialhaskell/stack/master/doc/img/hidden-warning.svg"></a></div>
 
-# stack vs cabal config files
+# stack.yaml vs cabal package file
 
 Due to their apparent overlap, the purpose of the following three files can be
 unclear:
 
 * `stack.yaml`
-* A cabal file, e.g. `my-package.cabal`
+* A cabal package file, e.g. `my-package.cabal`
 * `package.yaml`
 
 The last two are easy to explain: `package.yaml` is a file format supported by
-[hpack](https://github.com/sol/hpack#readme), which adds some niceties on top
-of cabal like YAML syntax support and automatic generation of `exposed-modules`
-lists. However, it's just a frontend to cabal files. So for this document,
-we're instead going to focus on the first two and try to answer:
+[hpack](https://github.com/sol/hpack#readme). It adds some niceties on top of
+cabal. For example, hpack has YAML syntax support and will automatically
+generate of `exposed-modules` lists. However, it's just a frontend to cabal
+package files. So for this document, we're instead going to focus on the first
+two and try to answer:
 
-_What's the difference between a `stack.yaml` file and a cabal file?_
+_What's the difference between a `stack.yaml` file and a cabal package file?_
 
 ## Package versus project
 
diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md
@@ -24,7 +24,7 @@ used, and `~/.stack/global-project/stack.yaml` is ignored.
 
 *Note 2:* A common source of confusion is the distinction between configuration
 in a `stack.yaml` file versus a cabal file. If you're trying to understand this
-breakdown, see [stack vs cabal config](stack_vs_cabal_config.md)
+breakdown, see [stack vs cabal config](stack_yaml_vs_cabal_package_file.md).
 
 ## Project-specific config
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,7 +19,7 @@ pages:
   - User guide: GUIDE.md
   - FAQ: faq.md
   - Configuration (Project and Global): yaml_configuration.md
-  - stack.yaml vs cabal config: stack_vs_cabal_config.md
+  - stack.yaml vs cabal package files: stack_yaml_vs_cabal_package_file.md
   - Build command: build_command.md
   - Dependency visualization: dependency_visualization.md
   - Docker integration: docker_integration.md
