| <HTML> |
| <HEAD> |
| <TITLE>Guidelines for working on www.netbeans.org</TITLE> |
| <META NAME="description" CONTENT="Guidelines specific to working on content on the www website"> |
| <link rel="stylesheet" type="text/css" HREF="../../netbeans.css"> |
| </HEAD> |
| |
| <BODY> |
| |
| <h1>Working With Content on www</h1> |
| |
| <UL> |
| <li><a href="#intro">Introduction</a> |
| <li><a href="#guidelines">Some Guidelines</a> |
| <ul> |
| <li><a href="#managed">Managed Content</a> |
| <li><a href="#new">New Content</a> |
| <li><a href="#naming">Naming Conventions</a> |
| <li><a href="#images">Images</a> |
| <li><a href="#bigimages">Big Images</a> |
| <li><a href="#binaries">Large Binary Files</a> |
| <li><a href="#links">Relative Links</a> |
| <li><a href="#dynamic">Dynamic Pages</a> |
| <li><a href="#style">Style and Formatting</a> |
| <li><a href="#breadcrumbs">Breadcrumbs</a> |
| </ul> |
| <li><a href="#perms">Got Permissions ?</a> |
| <li><a href="#updates">Submitting updates</a> |
| <li><a href="#offsite">Submitting Links to Off-Site Docs</a> |
| <li><a href="#translate">Translating Content</a> |
| <li><a href="#rightcol">The Right Column</a> |
| </UL> |
| |
| <h2><a name="intro">Introduction</a></h2> |
| <p>This guide is intended for anyone who would like to submit |
| content for the www.netbeans.org site (www specifically, not |
| the module websites like core.netbeans.org). "Submitting |
| content" might mean corrections or updates to existing docs, |
| completely new docs, or translated versions of some docs.</p> |
| |
| <p>The web-content repository is under SVN version control and can |
| be checked out. However the <a HREF="../teams/web/index.html">NetBeans Web Team</a> |
| have implemented a publishing system for www, and adding or editing |
| content there is quite different than for other module websites. |
| |
| <h2><a name="guidelines"></a>Some Guidelines</h2> |
| |
| <p>Please observere the following guidelines when commiting to the site : |
| |
| <ul> |
| |
| <li><a name="managed"></a> |
| <p><b>Managed Content?</b> |
| <br>The www website is partly "managed content", owned by the Web and |
| Evangelism teams. Any significant changes, or changes to higher-level |
| product info pages should be approved by the Evangelism and/or web teams |
| before publishing. If you're working on such a page, please forward your changes to |
| <a href="../../about/contact_form.html?to=1">webmaster</a> and the |
| <a href="../../about/contact_form.html?to=2">evangelism team</a>, |
| including some background about why you want to make these changes.</p> |
| |
| <li><a name="new"></a> |
| <b>New Content</b> |
| <br>Navigation and site layout is carefully controlled, to make sure |
| content is logically structured, in a coherent and consistent way. If |
| you are adding new content, please check with the |
| <a href="../../about/contact_form.html?to=1">webmaster</a> where would |
| be the best place to add your file(s), and how to link that with the |
| rest of the site. |
| |
| <li><a name="naming"</a> |
| <b>Naming Conventions</b> |
| <br>Again, if you are adding a <I>new</I> file, please try to use filenames |
| consistent with existing naming conventions. These are obviously not |
| critical, but please try to observe them. Some basic guidelines : |
| |
| <p><ul> |
| <li>Don't use spaces in file or directory names; |
| |
| <p><li>A NetBeans version number should not be needed in the filename. |
| Version-based directory structure is standard, so a filename need not |
| include a version number. Eg : |
| <blockquote>Good : kb/60/hello-world.html |
| <br><i>BAD : kb/hello-world-60.html</i> |
| </blockquote> |
| |
| <li>Don't use underscores (except for localised content language extension like index_ru.html). Eg : |
| <blockquote>Good : community/guidelines/file-naming.html |
| <br><i>BAD : community/guidelines/file_naming.html</i> |
| </blockquote> |
| |
| <!-- <li>Don't use mixed case in filenames (camelCase). Windows does not differentiante |
| between upper and lower case in filenames, which can cause problems and clashes in CVS. |
| See eg <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=57402">issue 57402</a> which |
| deals with this problem. Eg : |
| <blockquote>Good : file-name.html |
| <br><i>BAD : fileName.html</i> |
| <br><i>BAD : file.PNG</i> |
| <br><i>BAD : FILE.PNG</i> |
| </blockquote> --> |
| </ul> |
| |
| <li><a name="images"></a> |
| <b>Images</b> |
| <br>If you're adding images to the site, please |
| put them under the root images_www directory. If you're creating an article with |
| several images, it probably makes sense to create a new images dir for them, |
| e.g. images/articles/67/midp-guide/. |
| |
| <li><a name="bigimages"></a> |
| <b>Big Images</b> |
| <br> |
| Using wide images in your content will force |
| the page to be wide, and depending on a viewer's screen resolution this may |
| cause a horizontal scrollbar to appear - yuck! The minimum target resolution |
| netbeans.org is designed for is 1024 x 768px, which means the main content area |
| should be at maximum 600px wide. If you have any images wider than 600px, |
| please create scaled-down versions of them for use in your article. <br /> |
| To make sure visitors can see the real image |
| and any detail lost by the scaling, you should link the small version to |
| the fullsize version, so viewers can click to see it in all it's glory. |
| Here is an example: |
| <pre><a href="../../../images_www/articles/quickstart-web/palette.png"> |
| <img src="../../../images_www/articles/quickstart-web/palette_small.png" border="0"></a></pre> |
| |
| <br><br>If you're not comfortable resizing your images, the Web Team can help, |
| just <a href="../../about/contact_form.html?to=1">get in touch</a> |
| with details of what you need. |
| |
| <li><a name="binaries"></a> |
| <b>Large Binary Files</b> |
| <br>It is preferrable to keep large binary files <I>out</I> of the version controlled |
| repositories. If you need to put a big file on the site, for example a zipfile |
| of sources, a jar, or a .swf flash file, please use |
| <a href="https://netbeans.org/projects/help/pages/Downloads">the file upload feature</a>. |
| This utility allows uploading and maintenance of all kinds of files. Once your |
| file is in place, you can link to it from your html pages. |
| <br><br>If you don't have permissions to add a file to the utlity on www, you |
| could try adding it to contrib.netbeans.org. If you have no |
| permissions on any modules, contact the |
| <a href="../../about/contact_form.html?to=1">webmaster</a> with details of |
| what you're trying to do. |
| |
| <li><a name="links"></a> |
| <b>Relative Links</b> |
| <br>Please use relative links in your html, such as <a href="../../directory/file.html">, |
| rather than absolute (like "/directory/file.html") or fully qualified (like "https://netbeans.org/directory/file.html"). |
| This way your (and everyone else working on the site's) local checkout |
| is browseable, the links work, and go to your local copies. |
| |
| <li><a name="dynamic"></a> |
| <b>Dynamic Pages</b> |
| <br>While all content in web-content is static html, some pages are |
| automatically generated by a content management system, and then uploaded as static |
| snapshots. The home page is an example - several sections (headlines, |
| articles, etc) are generated and updated dynamically by the Web Team. |
| <em>Any edits you make to a dynamic page will be lost when the page will be |
| next auto-generated.</em> All such pages include a warning comment in the html |
| source : |
| |
| <blockquote><pre> |
| <!-- ====================================================== --> |
| <!-- Please do not edit this file by hand, it is rebuilt --> |
| <!-- automatically and your changes will be lost. Contact --> |
| <!-- webmaster for details. Rebuilt at --> |
| <!-- #TIMESTAMP# ................. --> |
| <!-- ====================================================== --> |
| </pre></blockquote> |
| |
| <p>If you see such a warning in a file, you will need to ask the |
| <a href="../../about/contact_form.html?to=1">webmaster</a> to make your changes.</p> |
| |
| <li><a name="style"></a><b>Style and Formatting</b> |
| <p>Please try to use standard styles, layout, and formatting for any new |
| pages. Please refer to the <a HREF="web-guide.html#templates">templates |
| section</a> of the webguide, and <a HREF="css-guide.html">the CSS guide</a> |
| for help. When in doubt, just copy the source of an existing page which suits |
| your needs.</p> |
| |
| <p><a name="breadcrumbs"></a><li><b>Breadcrumbs</b> |
| <p>The breadcrumb navigation trail across the top of the page is automatically |
| generated. The breadcrumbs are directory |
| based - as a visitor browses deeper into the site hierarchy, an item is |
| added to the breadcrumb list for each directory. </p> |
| |
| </ul> |
| |
| <h2><a name="perms"></a>Got Permissions ?</h2> |
| <p>If you have write permissions for web-content, and you are |
| comfortable with how the publishing system works, it's probably fine to |
| go ahead and commit your changes yourself. If you don't have permissions, |
| or are not 100% comfortable with SVN and/or HTML, please see the |
| <a href="#updates">Submitting Updates</a> section below.</p> |
| |
| <p>When your file is ready, the procedure to commit your files |
| is the same for any SVN commit.</p> |
| |
| <P><OL> |
| <LI>Checkout the website content (<b>web-content</b>). If you do : |
| |
| <P><TT>svn co https://svn.netbeans.org/svn/web-content~web-content/trunk</TT> |
| |
| <P>you will get the full website - including images, so it is quite |
| large and might take a while. |
| |
| <P><LI>Make your updates/additions. web-content/www maps to the docroot of |
| https://netbeans.org/, so for e.g. to edit |
| |
| <P><TT>https://netbeans.org/directory1/file2.html</TT> |
| |
| <P>look for the file |
| |
| <P><TT>trunk/web-content/www/directory1/file2.html</TT> |
| |
| <P>Edit or create your file and check your changes in a browser to |
| make sure all looks good. |
| |
| <P><LI>If you are editing and existing file, check nobody else has |
| edited the file since you started: |
| |
| <P><TT>$ svn update dir1/file2.html</TT> |
| |
| <P>If you are adding a new file, add it to the SVN repository: |
| |
| <P><TT>$ svn add dir1/file2.html</TT> |
| |
| <P>Assuming all is well, go ahead and commit it: |
| |
| <P><TT>$ svn commit -m "brief informative message about this update" dir1/file2.html</TT> |
| |
| <P>You can immediately view your changes on the web site, so double |
| check them. Browse to https://netbeans.org/dir1/file2.html . |
| |
| </OL> |
| |
| <p><h2><a name="updates">Submitting Updates</a></h2></p> |
| <p>If you don't have a netbeans.org account, or permissions to commit to web-content, |
| and you've found something on the site that needs updating, please |
| let us know about it. Even better, contribute the updated content! </p> |
| |
| <p>There are a few preferred methods for submitting updates - |
| using one of the following methods will help the webmasters to |
| quickly and easily verify your changes and apply them.</p> |
| |
| <UL> |
| <LI><B>Submit a patch for the HTML</B>. This is by far the easiest for the webmasters |
| and should ensure the fix is applied and goes live fastest. The following |
| example uses the Unix command line SVN, if you are using Windows or a GUI client |
| the basic procedure should be the same. |
| |
| <P><OL> |
| <LI>Checkout the website content. If you do : |
| |
| <P><TT>svn co https://svn.netbeans.org/svn/web-content~web-content/trunk</TT> |
| |
| <P>you will get the full website - including images, so it is quite |
| large and might take a while. |
| |
| <P><LI>Make your updates. Find the file you want to update. |
| trunk/web-content/www/ |
| maps to the docroot of https://netbeans.org/, so for eg to edit |
| |
| <P><TT>https://netbeans.org/directory1/file2.html</TT> |
| |
| <P>look for the file |
| |
| <P><TT>trunk/web-content/www/directory1/file2.html</TT> |
| |
| <P>Edit the file and check your changes in a browser to make sure all |
| looks good. |
| |
| <P><LI>Make the patch. Once you're done with your edits, from the |
| command line, do : |
| |
| <P><TT>$ cd trunk/web-content/www/ |
| <BR>$ svn diff -u directory1/file2.html > file2.patch</TT> |
| |
| <P>Replacing directory1 and file2.html with the real location and |
| filename of course. |
| |
| <P><LI>Submit your patch! Either file an issue, adding the patch as an |
| attachment, or simply email it to |
| <a href="https://netbeans.org/about/contact_form.html?to=1">webmaster</a>. |
| Please explicitly summarise what the patch is for, and why you |
| think it's needed. |
| </OL> |
| |
| <P><LI><B>Submit the whole updated HTML file</B>. If you'd rather |
| not use SVN or checkout the site, you can send in the updated |
| HTML file. |
| |
| <P><OL> |
| <LI>Browse to the print version of the page. First find the page on the |
| www site, and then click "printable version" at the top. |
| You'll see the same page, minus navigation, logos etc. |
| |
| <P><LI>Edit the HTML source. Select the View -> Source menu item |
| in your browser. Select all of the source, and save it as plain text file |
| somewhere on your system. Edit the page as you wish, and check your |
| changes in a browser to make sure all looks good. |
| |
| <P><LI>Submit the file! Either file an issue, adding the updated file as an |
| attachment, or simply email it to |
| <a href="https://netbeans.org/about/contact_form.html?to=1">webmaster</a>. |
| Please explicitly summarize what the updates are, and for which file, and why |
| you think it's needed. |
| </OL> |
| |
| <P><LI><B>Just submit the text of your updates!</B>. Obviously quickest |
| and easiest to do, but might take more time for the webmasters to check |
| and apply your suggestions. |
| </UL> |
| |
| <P><h2><a name="offsite">Submitting Links to Off-Site Docs</a></h2></p> |
| <p>If there's content hosted on some other site that you think is |
| relevant to netbeans.org, <a href="https://netbeans.org/about/contact_form.html?to=1">send us the link</a>, |
| including a brief description of what the article is about.</p> |
| |
| <P><h2><a name="translate">Translating Content</a></h2></p> |
| <p>If you're interested in translating either web content or the IDE itself |
| into your native language, we'd love your help. See the following guides |
| to get started :</p> |
| |
| <ul> |
| <li><a href="../contribute/localise.html">Translating html content for the netbeans.org website</a> |
| <li><a href="http://nblocalization.netbeans.org//">Translating the NetBeans IDE</a> |
| </ul> |
| |
| <P><h2><a name="rightcol">The Right Column</a></h2></p> |
| <p>To add content to the right column of a page on www, you need to put that |
| content in a special .inc file. The .inc file is not a standalone html file, |
| <b>it should not include any <head>, <title> or <body> tags!</b> |
| Just the content you want, eg styled text.</p> |
| |
| <p>The .inc file must live in the same directory as the main parent file. The |
| filename is critical - it should always take the form ${parent_filename}.inc.html. |
| This is perhaps best explained by looking at some examples :</p> |
| |
| <div style="float:left; padding-left:30px; width:300px; font-weight:bold;">For file ...</div><div style="margin-left:300px; font-weight:bold;">Put right col content in ...</div> |
| <div style="float:left; padding-left:30px; width:300px;">downloads.html</div><div style="margin-left:300px;">downloads.inc.html</div> |
| <div style="float:left; padding-left:30px; width:300px;">community/releases/roadmap.html</div><div style="margin-left:300px;">community/releases/roadmap.inc.html</div> |
| <div style="float:left; padding-left:30px; width:300px;">features/ide/index_ru.html</div><div style="margin-left:300px;">features/ide/index_ru.inc.html</div> |
| <div style="float:left; padding-left:30px; width:300px;">kb/60/using-netbeans/ant_zh_CN.html</div><div style="margin-left:300px;">kb/60/using-netbeans/ant_zh_CN.inc.html</div> |
| |
| |
| </body> |
| </html> |