Details

    • Type: New Feature New Feature
    • Status: Open Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Labels:
      None
    • Number of attachments :
      0

      Description

      (The following text was ripped from MSITE-281)

      Make changes (mostly typographic) intended to improve readability/consistency of the documentation. Some of the rules I chose to follow are surely controversial and a matter of taste:

      • Hyperlinks should be readable/understandable without their surrounding context (a best practice for web design, e.g. see Stanford Online Accessibility Program)
      • Headline style capitalization for page/section titles (see also Capitalization of Headings and Titles)
      • Double quotation marks instead of single quots for quoted text (Quotation Marks and Direct Quotations)
      • Proper casing for acronyms (e.g. POM instead of pom, but scp if one wants to refer to the protocol part of a URL literally)
      • Monospaced font for file/path names, URLs, plugin goals, command prompts
      • Uppercase first letter for plugin names (it might just be my German habit, but I consider "the Clean Plugin" more understandable than "the clean plugin" since I can realize the reference to a name more quickly)

      It might by worth to create some guidelines (house-style) that Maven developers can follow for their documentation, similar to the Maven Plugin Documentation Standard and the code formatter style.

        Activity

        Hide
        Benjamin Bentmann added a comment -
        • exactly one top-level heading per page which matches the title of the page, all other headings should have a deeper level, e.g. Project Information good, Source Repository not so good.
        Show
        Benjamin Bentmann added a comment - exactly one top-level heading per page which matches the title of the page, all other headings should have a deeper level, e.g. Project Information good, Source Repository not so good.

          People

          • Assignee:
            Unassigned
            Reporter:
            Benjamin Bentmann
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated: