SEARCH:
NAVIGATION:
This page describes methodologies, standards, and design considerations for the CleanCode website, as well as provides a behind-the-scenes look on constructing a website.
As far as the style of CleanCode, these points are notable:
Creating a web page is a terribly simple task. Many programs, including most Microsoft Office products, will create a web page for you at the click of a button. Constructing a website, by contrast, is a labor-intensive, complex task filled with minutiae. That is, modeling the intricacies of relationships between pages and between sections, providing intra-site navigation that is both effective and easy to use, designing for ease-of-use for people with varying technical abilities, coping with the variety of browser platforms available, not to mention just keeping your off-site links current... all require a significant degree of skill. An artist can use the simplest graphics program, such as Microsoft Paint, to create dazzling illustrations. It is not the program; it is the skill of the person, that creates. The point is that while there are tools to create an entire website for you, do not expect miracles. For miracles, you have to get your hands "dirty".
If you are a developer wishing to create open-source software, SourceForge.net--the host of the CleanCode web site--is an excellent place to start. SourceForge provides comprehensive support facilities for open-source software projects, saving you from having to re-invent the wheel for a significant portion of services common to all websites--mailing lists, discussion forums, release mechanisms, visitor statistics, access control, version control, and more. Even so, there is a significant road ahead.
The first illustration diagrams a semi-generic process for constructing a website on SourceForge. This is an idealized process flow, from the top of the page to the bottom. In practice there will be a variety of refinement loops where you proceed from one step to the next before it is finished, then go back and make enhancements and corrections. Usually you will go two steps forward, one step back. Occasionally, you'll go just one one step forward, then two steps back. Eventually you will work through the entire process. In the illustration (click on it to open the full size PDF file), each process step is indicated by a grey box. The salmon boxes provide specifics (URLs, file paths, email addresses, and command invocations) to supplement many of the process steps. I called this semi-generic because it does reflect my own experience and preferences. I include a search engine installation that is a well-designed, clean (of course!) package from xav.com. You may wish to use a different one, or none at all. I also include a visitor tracking facility, again from xav.com, that provides much more details than SourceForge's standard statistics. I include references to winCVS and WinSCP, both de facto standards, but again, not required. There is just one piece that is a CleanCode original (remoteExplorer in the diagram--now called Server File Explorer). This is a simple Windows Explorer-like tool that supplements WinSCP with just a couple functions that are quite useful (to me), notably: the tree view, allowing a view of all files in any subtree, and the history mechanism, marking files that are new since the previous visit.
The illustration at right looks at the CleanCode website from a different perspective. If you create a website according to clean coding guidelines, be it from CleanCode or other sources, your website should be easy to maintain. This chart illustrates a part of that process. On the right side of the page, a conceptual view of the CleanCode web site is shown, consisting of essentially a collection of HTML files, plus a collection of specification and control files.
The left side shows the inputs and processes used to generate these, allowing you to define something (like a page header) just once, and then automatically propagate it through the website. Then if you wish to update the header, update just the original, then again propagate it through the site. A second key aspect of maintenance is navigation. If you add a couple pages here, delete a page there, or perhaps move a subdirectory, it is necessary to update all the links that refer to those. The Java SDK-supplied tool javadoc, used to generate Java documentation from Java source files, as well as the CleanCode tool pod2htmltree, used to generate Perl documentation from Perl source files, automatically take care of regenerating navigation links in their respective APIs. Those are, of course, specialized for API generation. The other CleanCode tool XmlTransform is a more general purpose site generation tool that will automatically add navigation to any of your regular web pages. The navigation buttons at the top of this web page, and all hand-written web pages on CleanCode, were automatically inserted by XmlTransform.
For a complete behind-the-scenes look at CleanCode--including graphical documentation of the XML Schema and the Ant build file--take a look here.
