You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Dennis Lundberg (JIRA)" <ji...@codehaus.org> on 2008/03/23 00:01:45 UTC
[jira] Created: (MNGSITE-43) Create writing style guidelines
Create writing style guidelines
-------------------------------
Key: MNGSITE-43
URL: http://jira.codehaus.org/browse/MNGSITE-43
Project: Maven Project Web Site
Issue Type: New Feature
Reporter: Benjamin Bentmann
(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|http://soap.stanford.edu/show.php?contentid=46])
- Headline style capitalization for page/section titles (see also [Capitalization of Headings and Titles|http://www.tc-forum.org/topicmai/ml03capi.htm])
- Double quotation marks instead of single quots for quoted text ([Quotation Marks and Direct Quotations|http://www.informatics.sussex.ac.uk/department/docs/punctuation/node30.html])
- 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|http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation] and the code formatter style.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (MNGSITE-43) Create writing style guidelines
Posted by "Benjamin Bentmann (JIRA)" <ji...@codehaus.org>.
[ http://jira.codehaus.org/browse/MNGSITE-43?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=146323#action_146323 ]
Benjamin Bentmann commented on MNGSITE-43:
------------------------------------------
- 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|http://maven.apache.org/plugins/maven-invoker-plugin/project-info.html] good, [Source Repository|http://maven.apache.org/plugins/maven-invoker-plugin/source-repository.html] not so good.
> Create writing style guidelines
> -------------------------------
>
> Key: MNGSITE-43
> URL: http://jira.codehaus.org/browse/MNGSITE-43
> Project: Maven 2 Project Web Site
> Issue Type: New Feature
> Reporter: Benjamin Bentmann
>
> (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|http://soap.stanford.edu/show.php?contentid=46])
> - Headline style capitalization for page/section titles (see also [Capitalization of Headings and Titles|http://www.tc-forum.org/topicmai/ml03capi.htm])
> - Double quotation marks instead of single quots for quoted text ([Quotation Marks and Direct Quotations|http://www.informatics.sussex.ac.uk/department/docs/punctuation/node30.html])
> - 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|http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation] and the code formatter style.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira