User: kjenks Date: 00/11/05 21:45:52 Added: . DOCUMENTATION_STANDARDS.html Log: A few little documentation standards. See Bug#133 et al. Revision Changes Path 1.1 jbossweb/DOCUMENTATION_STANDARDS.html Index: DOCUMENTATION_STANDARDS.html =================================================================== <H2>jBoss Documentation Standards</H2> <P>This document is intended for Open Source developers who are helping with documentation for the <A HREF="http://jboss.org/">jBoss Project.</A></P> <P>First, the name. To maintain consistency and to improve our chances of maintaining a trademark on everything, please make sure you use a lower-case j and an upper-case B, "jBoss," even at the beginning of a sentence.</P> <P>This project uses CVS for version control. Make sure you check out the latest docs from CVS module jbossweb (not just downloading the files from the Web site) and check them back in when you're done. If you make modifications to the files you download from the Web or FTP servers, you may be modifying an obsolete file. See the <A HREF="cvs.htm">jBoss CVS</A> page for details.</P> <P>If you don't have CVS commit privledges, you can e-mail your changes to <A HREF="mailto:[EMAIL PROTECTED]">marc fleury</A> or <A HREF="mailto:[EMAIL PROTECTED]">the jBoss Developer's mailing list.</A></P> <P>If you're making changes to the jBoss code, you must document every class, every method, and every public member variable with Javadoc-style comments. See the <A HREF="http://java.sun.com/products/jdk/javadoc/index.html">Javadoc Tool Home Page</A>, especially <A HREF="http://java.sun.com/products/jdk/javadoc/writingdoccomments.html">How to Write Doc Comments for Javadoc.</A> These comments will be included in the Javadoc-generated documentation for jBoss, which come with the jBoss source distribution (in the docs/api/ directory). You should also follow <A HREF="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">the official Sun Java Coding Conventions.</A></P> <P>Before you modify the other documentation on the jBoss Web site, please take a few minutes to roam around the other documents and get a feel for their format. View the HTML source, look under the hood and kick the tires. We're striving for a consistent, professional look, and it will help if you're familiar with the other documents.</P> <P>There are four categories of user-interface text that should have special formatting:</P> <UL> <LI>Directory and file names (fixed font, black on white, use <CODE> and </CODE> tags) <LI>Class names, JNDI names, etc. (fixed font, black on white, use <CODE> and </CODE> tags) <LI>Things that the user should type (or copy/paste) at the command line (fixed font, black on a greenish background, BGCOLOR="#80FF80") <PRE><TABLE BORDER=0 BGCOLOR="#80FF80" CELLSPACING=4><TR><TD><PRE></PRE> <LI>Expected output (fixed font, black on a yellowish background, BGCOLOR="#FFFF80") <PRE><TABLE BORDER=0 BGCOLOR="#FFFF80" CELLSPACING=4><TR><TD><PRE></PRE> </UL> <P>Although it's not strictly necessary, please consider using UPPER-CASE for all HTML tags and indent your HTML code. (It makes the HTML source much easier for future developers to read.)</P> <P>Use the standard link colors and styles, like underlined blue text for <A HREF=...> tags. Experienced Web users (like our target audience) know these visual cues. </P> <P>Commands that the user should type should be a fixed-width font, formatted so that the user can copy the commands from the Web browser to the command line.</P> <P>There was an earlier attempt at rounded-rectangle graphic standardization, with dark yellow sidebars, like <A HREF="news0400.htm">this 'older news' page.</A> The rounded-rectangle graphics and TABLE formats are pretty hard to describe and hard to follow in an Open Source development project, so we'll move away from those graphical standards to a simpler design.</P>
