Structure of the specs in Confluence for good living documentation

[johnboyes]

The primary goal of this gauge-confluence plugin is to provide good "living documentation" in Confluence.

This very nice SpecFlow blog article has some great proposals on what good living documentation for spec by example looks like.

Plan is for the gauge-confluence plugin to adopt the same principles/conventions as in the SpecFlow article, which leads to the following proposals:

• the page name for a spec in Confluence will be the spec's heading
  • page names should also be short for browseability. We could just take the first x characters of the heading, not sure about that though. Might be better just to recommend short spec headings to users of the plugin? And/or could take just the first sentence of the Gauge spec heading as the page name in Confluence? That would allow headings to be more detailed in Gauge if need be, but still concise in Confluence.
• how to balance short page names with the Confluence requirement for each page's name to be unique?
  • have a convention that each git repo publishes its specs to its own dedicated Confluence space (or spaces), i.e. convention is that multiple git repos should not publish their specs to the same space
  • have a convention that every spec heading and also every spec directory in a given repo has a unique name
  • duplicates will result in the duplicates not being published to Confluence
  • duplicates will be flagged in the plugin's output when it runs, along with a recommendation to rename the duplicates in git and then republish
  • requiring there to be no duplicates is a sensible (if opinionated) restriction, as it helps to make the living documentation easier to navigate
  • if we were to allow duplicate headings, we'd have to work around it by (for instance) appending the spec's unique GitHub path to the page name. This would make the page name very long and have the following negative effects:
    • the page names would be more difficult to read/scan, and hence to establish the intent
    • the page tree views would also be cluttered with the long page names and suffer from the same problem of readability
• (post-MVP) we could have a "dry run" mode for the plugin where it identifies duplicates without publishing anything
  • this dry run mode could also be incorporated into automatic commit / pull request checks, to ensure that duplicates are caught at source and can be fixed