Working With Content on www

• Introduction
• The Publishing System
• Some Guidelines
  • Commit to testwww
  • Managed Content
  • New Content
  • Naming Conventions
  • Images
  • Big Images
  • Large Binary Files
  • Relative Links
  • Dynamic Pages
  • Style and Formatting
  • Breadcrumbs
• Got Permissions ?
• Submitting updates
• Submitting Links to Off-Site Docs
• Translating Content
• The Right Column

Introduction

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.

www is a module website in CVS just like any other, and can be checked out. However the NetBeans Web Team have implemented a publishing system for www, and adding or editing content there is quite different than for other module websites.

The Publishing System

Basically, the "content" part of any www page is commited to a staging server at testwww/www. You can browse the content there at http://testwww.netbeans.org/ (though that site is not exposed publicly or linked from anywhere). Note that none of the headers, footers, or navigation appear there. The publishing system reads content from that site, wraps it in navigation templates, and publishes it to the live site at www/www/.This means that all changes or additions should be made on testwww/www/! Never commit to www/www/.

The only exceptions are buildmasters and release engineers who may need to commit to special directories like www/www/updates/ and www/www/download/.

Some Guidelines

Please observere the following guidelines when commiting to the site :

• Commit to testwww!
  Remember all changes should be made to the staging site testwww, not www, as described in the publishing system above.

• Managed Content?
  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 webmaster and the evangelism team, including some background about why you want to make these changes.

• New Content
  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 webmaster where would be the best place to add your file(s), and how to link that with the rest of the site.

• Naming Conventions
  Again, if you are adding a new 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 :
  • Don't use spaces in file or directory names;

  • 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 :

    Good : kb/60/hello-world.html
    BAD : kb/60/hello-world-60.html

  • Don't use underscores (except for localised content language extension like _ru.html). Eg :

    Good : community/guidelines/file-naming.html
    BAD : community/guidelines/file_naming.html

  • 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 issue 57402 which deals with this problem. Eg :

    Good : file-name.html
    BAD : fileName.html
    BAD : file.PNG
    BAD : FILE.PNG

• Images
  The hosting infrastructure that runs netbeans.org only allows browsers to cache content served from certain directories, like images/. An image served from any other location on the site is resent every time a user requests it. This has caused very significant server load and traffic issues. If you're adding images to the site, please put them under the root images/ dir. If you're creating an article with several images, it probably makes sense to create a new images dir for them, eg images/articles/midp-guide/.

• Big Images
  With the site's 2-column layout, available width in the center column is relatively restricted. Using wide images in your content will force the page to be wide, and depending on a viewer's screen resolution 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. Eg if you have an image named editor.png say that is 650px wide, please create a 600px or smaller size version - name it for eg editor-small.png, and display it in your article. 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. For an example see the JMX Getting Started Guide.
  
  If you're not comfortable resizing your images, the Web Team can help, just get in touch with details of what you need.

• Large Binary Files
  It is preferrable to keep large binary files out of the CVS repository. 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 consider using the SourceCast file upload utility. 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, rather than commiting it to CVS.
  
  If you don't have permissions to add a file to the utlity on www, you could try adding it to another module site - eg if you are the xyz.netbeans.org site owner, you will have permissions to use the xyz file upload utility at http://xyz.netbeans.org/servlets/ProjectDocumentList. If you have no permissions on any modules, just contact the webmaster with details of what you're trying to do.

• Relative Links
  Please use relative links in your html, eg <a href="../../directory/file.html">, rather than absolute (like "/directory/file.html") or fully qualified (like "http://www.netbeans.org/directory/file.html"). This way your (and everyone else working on the site's) local testwww checkout is browseable, the links work, and go to your local copies.

• Dynamic Pages
  While all content in testwww/www/ is static html, some pages are automatically generated off-line, and then commited to cvs as static snapshots. The home page is an example - several sections (headlines, articles, etc) are generated and updated dynamically by the Web Team. Any edits you make to a dynamic page would be lost when the page was next auto-generated. All such pages include a warning comment in the html source :

    <!-- ====================================================== -->
    <!-- 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# .................                          -->
    <!-- ====================================================== -->
    

  
  
  If you see such a warning in a file, you will need to ask the webmaster to make your changes.

• Style and Formatting
  Please try to use standard styles, layout, and formatting for any new pages. Please refer to the templates section of the webguide, and the CSS guide for help. When in doubt, just copy the source of an existing page which suits your needs.

• Breadcrumbs
  The breadcrumb navigation trail across the top of the page is automatically generated based on the presence of meta tags. The breadcrumbs are directory based - as a visitor browses deeper into the site heirarchy, an item is added to the breadcrumb list for each directory where the index file includes the NAV_LINK meta. This meta tag specifies the text to use for the breadcrumb. Eg if some/dir/index.html includes the line :
  
  <meta name="nav_link" content="Features">
  
  then all pages in some/dir/ will include a linked "Features" breadcrumb.

Got Permissions ?

If you have CVS write permissions for www and testwww, 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 CVS and/or html, please see the Submitting Updates section below.

When your file is ready, the procedure to commit your files is the same for any CVS commit.

1. Checkout the website content (testwww!). If you do :

      $ cvs -z4 co testwww/www

   you will get the full website - including images, so it is quite large and might take a while.

2. Make your updates/additions. testwww/www/ maps to the docroot of http://www.netbeans.org/, so for eg to edit

      http://www.netbeans.org/directory1/file2.html

   look for the file

      testwww/www/directory1/file2.html

   Edit or create your file and check your changes in a browser to make sure all looks good.

3. If you are editing and existing file, check nobody else has edited the file since you started :

      $ cvs update dir1/file2.html

   If you are adding a new file, add it to CVS :

      $ cvs add dir1/file2.html

   Assuming all is well, go ahead and commit it :

      $ cvs commit -m "brief informative message about this update" dir1/file2.html

   You can immediately view your changes on the testwww site, so double check them. Browse to http://testwww.netbeans.org/dir1/file2.html.

   From here, the publishing system will automaticlaly propagate your changes to the live www site. This will happen within 1 hour.

Submitting Updates

If you don't have a CVS account, or permissions to commit to www, and you've found something on the site that needs updating, please let us know about it. Even better, contribute the updated content! Remember all updates should be made against testwww, rather than www, as described in the publishing system section above.

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.

• Submit a patch for the HTML. 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 CVS, if you are using Windows or a GUI client the basic procedure should be the same.
  1. Checkout the website content. If you do :

        $ cvs -z4 co testwww/www

     you will get the full website - including images, so it is quite large and might take a while.

  2. Make your updates. Find the file you want to update. testwww/www/ maps to the docroot of http://www.netbeans.org/, so for eg to edit

        http://www.netbeans.org/directory1/file2.html

     look for the file

        testwww/www/directory1/file2.html

     Edit the file and check your changes in a browser to make sure all looks good.

  3. Make the patch. Once you're done with your edits, from the command line, do :

        $ cd testwww/www/
        $ cvs diff -u directory1/file2.html > file2.patch

     Replacing directory1 and file2.html with the real location and filename of course.

  4. Submit your patch! Either file an issue, adding the patch as an attachment, or simply email it - as an attachment - to webmaster. Please explicitly summarise what the patch is for, and why you think it's needed.

• Submit the whole updated HTML file. If you'd rather not use CVS or checkout the site, you can simply send in the update HTML file.
  1. Browse to the testwww version of the page. First find the page on the normal www site, and then in the location bar of your browser change www to testwww. Eg, if the problem page is at :

        http://www.netbeans.org/directory1/file2.html

     then edit the URL to read :

        http://testwww.netbeans.org/directory1/file2.html

     and hit return - you'll see the same page, minus navigation, logos etc.

  2. Edit the HTML source. Select the View -> Source menu item in your browser. Select all of the source, and save it as plain text somewhere on your system. Edit the page as you wish, and check your changes in a browser to make sure all looks good.

  3. Submit the file! Either file an issue, adding the updated file as an attachment, or simply email it - as an attachment - to webmaster. Please explicitly summarise what the updates are, and for which file, and why you think it's needed.

• Just submit the text of your updates!. Obviously quickest and easiest to do, but might take more time for the webmasters to check and apply your suggestions.

Submitting Links to Off-Site Docs

If there's content hosted on some other site that you think is relevant to netbeans.org, send us the link, including a brief description of what the article is about.

Translating Content

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 :

• Translating html content for the netbeans.org website
• Translating the NetBeans IDE

The Right Column

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, it should not include any <head>, <title> or <body> tags! Just the content you want, eg styled text.

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 :