Help Page(s) for This Site
Please note that the material on this page is evolving. We kindly ask for your patience as we work to improve the content necessary to make this page as valuable as possible to its readers.
Help Page Topics
- NOUNZ Overview
- Technical Requirements and Installation
- Input Configuration and Data Source Files
- Execution: Compiling Your Data and Generating Web Sites
- Navigation and Use
Welcome to the NOUNZ Data Compilation Platform. Very simply, NOUNZ takes your enterprise Data and compiles it into a Web Site. This very Web Site is an example of such a compilation process.
Your Data is made visible to the NOUNZ Compiler in the form of Comma Separated Value (CSV) files, where each file represents a homogeneous grouping or inventory of Noun Instances (sometimes referred to as Configuration Items). Each grouping or inventory is referred to as a Noun Type (sometimes referred to as a Configuration Type or Configuration Item Type).
Once your Data and some basic configuration information for the compilation are made visible, the NOUNZ Compiler is executed. It reads all your Noun Instances from each of your Noun Type files and uses some rules you specify to generate or synthesize a highly organized and feature rich Web Site, like this one. All individual Noun Instances are registered with their domain specific Noun Type Catalogs and all domain specific catalogs are registered with the Master Catalog (visible from the main menu bar). Most Noun Type catalogs are also made available via the Left Side Navigation Bar, for quicker access.
In addition to being registered with each appropriate catalog, each Noun Instance is also given multiple views to make it easier for you, the end user, to see and understand your enterprise data. As you drill into specific Noun Instance pages, you'll see that each is given a Home Page, Semantic Relationship Views, Tabular Views, visual Node Cluster Views, and much more.
The NOUNZ Compiler also generates interactive Dashboards for each Noun Type, made accessible via the Dashboards menu item, along the top menu bar.
One of the things that makes NOUNZ very different from other platforms is its ability to harvest Semantic Relationships from your Data. A Semantic Realtionship is a relationship that has some level of descriptive context that allows the reader to better understand how and why any two things are tied together. NOUNZ harvests such relationships and uses them to generate rich linkages between pages, throughout the entire site. Because a computer harvests these links, instead of a human, it means you get many more meaningful linkages between Web Pages, detailed connectivity reports, far fewer dead links, and a much more advanced Web Site user experience.
Technical Requirements and Installation
The skills you will require to install, run and maintain NOUNZ...
- You will need to know how to work with Software Compilers, just like a typical Software Developer. This means you need to be able to perform the basic functions of being able to install and run software.
- You will need to know how to scrub/cleans and transform data. This is common when taking data from any one source system and converting it to be compatible for any other target system. Beginners can do this using simple features in your spreadsheet tool. Advanced users will use scripting languages to do so. In some cases, you may even want to use Extract, Transformation, and Load (ETL) tools to do so. We've found that people who understand scripting languages usually do very well because they can transform data much faster and more efficiently than those who perform such tasks, manually.
- You will need to understand HTML, as you will start to enrich your source Data will HTML to make it more powerful.
- You will need to understand the concept of Primary Keys, which are used to make things like data records or objects unique. We'll help you learn this set of skills, if you don't have them, already.
The technologies you "will" require to install, run and use the NOUNZ Compiler...
- A Computer: The demonstration site (http://nounz.if4it.com) that you're looking at, right now, was generated using a simple Apple Mac-Air laptop, in a few minutes. You can opt to use any computer that supports the following technical components, listed further below. Since NOUNZ is a "compiler," the more CPU, Memory, I/O, and Storage you provide, the better it will run. However, you can start small (i.e. on a laptop or desktop) and work your way up to more advanced computing hardware, should you rquire it. Our testing has shown that rebuilding a Web Site that is comparable to the size of Wikipedia can be done in about 5 to 6 hours, on an Apple Mac-Air laptop.
- Operating Systems Requirements: NOUNZ always works best on a Unix based Operating System, such as Mac OSX or Linux. However, you should be able to also install and run NOUNZ on any computer that supports the Ruby language interpreter and runtime environment.
- Runtime Language: The NOUNZ Compiler was built with and runs (or executes) using the Ruby programming language and runtime environment. Like other compilers, such as a Java Compiler, a C++ Compiler, or a C# Compiler, the NOUNZ Compiler requires that you first install the base language development and runtime environments on your computer. To do so, search for "Install Ruby" on a major search engine and you will find detailed directions that will walk you through how to properly install and test the Ruby language interpreter on your own computer. Or, you can go directly to https://www.ruby-lang.org/en/downloads/ and follow the directions on that web site.
- Additional Ruby Library Components: In Ruby, reusable software library components are called "Gems." The NOUNZ Compiler requires that you install a Gem known as "FasterCSV." This Gem will enable NOUNZ to read your CSV files, both, faster and more efficiently than the base language does. Simply go to the site: install the Ruby Gem known as FasterCSV and follow the directions to install the FasterCSV Gem.
- The NOUNZ Compiler: In order to compile your Data into Web Sites, you will also require the installation of the NOUNZ Compiler, on your computer. Refer to the installation directions for NOUNZ, further in this section.
- Spreadsheet Tool: While optional, we recommend that you use your favorite spreadsheet development and management tool to create, coordinate, and test data that you can quickly and easily save to Comma Separated Value (CSV) format, which is what NOUNZ expects to see, when it reads your Data.
The technologies you "will not" require for NOUNZ... (We love to remind everyone of the many tools and technologies you won't need to install, run, and use NOUNZ, making it far simpler than competing tools.)
- Database Servers: You will not need to install, run, and maintain a Database Schemas, Database Servers, and all their related infrastructure.
- Application Servers: You will not need to install, run, and maintain complex Application Servers and all their related infrastructure.
- Web Servers: Web Servers are optional and are only necessary if you want to share the compiled output with broader communities of people.
Installing NOUNZ on your computer...
- Once you have Ruby and FasterCSV installed and available, copy the IF4IT_NOUNZ.tar.gz file to a local directory on your computer.
- Once the NOUNZ package is on your computer, uncompress it using the command "gzip -d IF4IT_NOUNZ.tar.gz".
- Once it's uncompressed, unpack it using the command: "tar -xvf IF4IT_NOUNZ.tar". Doing so will create directory called "IF4IT_NOUNZ" that will contain all components that come with the NOUNZ Compiler.
- You should now change directory into the directory "./IF4IT_NOUNZ/INTRANET/SOURCE_CODE" using the command: "cd ./IF4IT_NOUNZ/INTRANET/SOURCE_CODE".
- You can now build the data provided to you as part of the default package by running the command: ". buildSource.sh"
Once you've properly installed and uncompressed the NOUNZ package, you will see the following sub-directories...
- DOCS: is where the IF4IT installs any documentation that is for the users.
- HTML: is where the compiler generates/synthesizes its output.
- LOGS: is where the compiler generates its runtime/execution log file(s).
- SOURCE_CODE: is where all obfuscated source code and scripts are located.
- USER_DATA: is where the user can customize his/her data.
Input Configuration and Data Source Files
The NOUNZ Compiler uses Comma Separated Value (CSV) format as its primary means of formatting data that is supplied to the compilation process. CSV was chosen for a number of reasons. First, CSV format is very common. Second, CSV format is easily generated from readily available common spreadsheet software that can save spreadsheets directly to CSV format. Finally, because spreadsheet tools can easily generate CSV, it becomes a very simple means of getting NOUNZ users up and running, as fast as possible, without them having to be too technical.
Template Spreadsheets and CSV Files: NOUNZ is distributed with many pregenerated spreadsheets and and CSV files that act as easy to use templates and which are intended to help NOUNZ users get up and running as quickly as possible. Templates not only help NOUNZ users develop Web Sites quicker but they also act as learning tools because they help NOUNZ users see working examples of how to structure, both, data and rules for the compiler to execute without errors.
Input Data Categories: Input data for the NOUNZ Compiler is broken into two distinct types of data... (1) Administrative CSV Files and (2) Core Data CSV Files.
(1) Administrative CSV Files: These files are used to provide the NOUNZ Compiler with administrative data that controls the look, feel, layout, navigation, and construction of resulting Web Sites. Administrative data is fed to the compiler via a number of files that each have specific structure and intent...
- Config.csv: This file, which gets saved in the "USER_DATA/CONFIG" directory, allows you to control the Look and Feel of the Web Site(s) that get generated (i.e. colors, logos, images, etc.).
- NounList.csv: This file, which gets saved in the "USER_DATA/NOUNS" directory, allows you to define each Noun Type (I.e. Data Type) and specify things like input source directories, output directory names (for HTML file storage), primary keys, etc.
- NounIndexes.csv: This file, which gets stored in the "USER_DATA/INDEXES" directory, allows you to tell the compiler to "index" certain attributes within a given Noun Type (indexes show up in catalogs, just like a a traditional library). Users can index Noun Instances by any column name.
- NounRelationships.csv: This file, which gets saved to the "USER_DATA/RELATIONSHIPS" directory, allows you to register and define "additional" Noun to Noun Relationships that you'd like to load into the system. These Relationships are "user defined relationships" that go above and beyond that the compiler can discover, through simple rules.
NOTE: The column names in these Administrative CSV Files are meaningful to the compiler and, therefore, cannot be changed by a user.
(2) Core Data Files: These files are used to provide your "data" to the NOUNZ Compiler and are broken into three categories. Main Site Pages, Noun Data Files, and Relationship Data Files...
- Main Site Pages: These CSV files allow you to publish basic content to the core site pages like "Home", "Support," "Help" that are located on the main header navigation bar. The Home.csv file, the Support.csv file, and the Help.csv file all get saved in the "USER_DATA/ROOT_HTML" directory.
- Noun Data Files: These CSV files act as "homogeneous" inventories of Noun Instances that are of a specific Noun Type. Think of each of these files as a "container" of all instances of a single Noun Type, where each Row represents a Noun Instance and every column represents a descriptive attribute for that Noun Instance. So, for example, Applications.csv is an inventory of all Application instances, Capabilities.csv is an inventory of all Capabilities, Resources.csv is an inventory of all human Resources, Organizations.csv is an inventory of all Organizations, etc. Each of these inventory CSV files gets saved with the master NounList.csv file, in the "USER_DATA/NOUNS" directory.
- Relationship CSV Files: These CSV files allow a user to manually specific "additional" or "explict" Relationships that are loaded into the NOUNZ Compiler, in addition to those Relationships that are discovered by the compiler, itself. A user can create and register as many explicit relationship files as he/she wishes and name them all differently, taking the form "USER_DEFINED_NAME.csv". All Relationship CSV Files must be registered within the "Relationships.csv" file and need to be saved in the "USER_DATA/RELATIONSHIPS" directory, along with the Relationships.csv.
Execution: Compiling Your Data and Generating Web Sites
Once both your Administrative Data CSV Files and your Core Data CSV Files are saved in their appropriate directories, under the "USER_DATA" directory, you can run the NOUNZ Compiler to create your Web Site.
- Obfuscated source code is located in the directory "SOURCE_CODE"
- You can run the NOUNZ Compiler by executing the command "ruby if4it_nounz.rb".
- The results of compilation will either be successful (i.e. Pass) and the compiler will run to completion or a failure (i.e. "Fail"), which will cause the compiler to abort at the point of failure.
- Progress of the compiler's execution can be found in the "LOGS/log.txt" file.
(1) Pass: Means the compiler ran successfully. Details of the execution, along with any benign warnings, show up in the "LOGS/log.txt" file.
Successfully generated Web Sites get automatically put into the "HTML" directory.
Successfully generated Web Sites automatically create a site that takes the form of an "Electronic Library" of your data. If you know how to use Card Catalogs in a traditional library, you know how to navigate a NOUNZ generated Web Site.
Upon successful completion, the resulting Web Site will automatically include the following constructs:
- Master Catalog (made available in the top header navigation menu bar).
- Domain Catalogs (per Noun Type and made available via the Master Catalog and the Left Navigation Page.
- Aggregate Views of Noun Types: (alphabetic lists, Tabular Views, Density Views, Relationship Views, etc.)
- Indexes within Domain Catalogs (that the user specified in the NounIndexes.csv file, along with some default/build-in Indexes that get generated based on out-of-the-box data types).
- Individual Noun Instance View Pages: Textual Lists, Enriched Tables, Visual Node Clusters, Views of Semantic Relationships, etc.
- Dashboards (made available in the top header navigation menu bar).
(2) Fail: Means the compiler aborted due to any number of possible error conditions.
Primary error messages get published directly to the execution screen and a user can look in the "LOGS/log.txt" file to see details of execution and place of failure.
Failure means there is something wrong in your configurations, your rules, or in columns that you identify as Noun Keys.
A failed compiler execution can occur for a number of common reasons, including but not limited to...
- Incorrect data in one or more of your Administrative CSV Files.
- Incorrect data in one or more of your Core Data CSV Files.
- Files not being placed in their proper directories.
- Incorrect Primary Keys that help uniquely identify each Noun Instance, within a Noun Type.
Compiler Generated Warnings: Warnings are notes to the person doing the compiling that point out areas of concern or things that can be improved. Warnings do not cause compiler failure and will not hinder the compiler's compilation process from reaching success. All warnings show up in the "LOGS/log.txt" file. The most common type of warning issued by the NOUNZ Compiler is when a rule to discover Relationships is executed and the compiler cannot find and create a Relationship where it thinks there should be one.
Navigation and Use
Site navigation is controlled via two key constructs...
- the Main Menu Bar
- the Left Column Navigation Pane
1. The Main Menu Bar: This is the horizontal colored strip that shows up toward the top of each page that contains linked pages called "Home", "Catalog", "Dashboards", "Support", and "Help". Each of these constructs gets generated, automatically, as part of the compilation process.
- Home: This HTML link leads the end users back to the administrator generated "Home Page" of the Web Site that was generated by the NOUNZ Compiler.
- Catalog: This HTML link functions like an automatically generated "Master Catalog" that is similar but more comprehensive than traditional Web Site "Site Maps." It leads the end user to a comprehensive catalog of all key constructs that are included in the NOUNZ generated Web Site. Look to this page to grow, over time, to include more and more features, as they get developed by the IF4IT.
- Dashboards: This HTML link leads the users to a comprehensive inventory of all compiler generated Noun Type related "Dashboards Page." Every Noun Type you register with the NOUNZ Compiler, via the "NounList.csv" file, will yield a Dashboard for that Noun Type.
- Support: This HTML link leads end users to an administrator defined "Support Page," which should be populated with the information about yourself or your own organization that the end users will need in order to contact someone for help about the Web Site that was generated and that they're currently using.
- Help: This HTML link leads end users to a compiler generated "Help Page" (i.e. this page), where they can find details about the NOUNZ Compiler.
2. The Left Column Navigation Pane: This is the column of HTML links that shows up along the left hand side of every Web Page that is generated by the NOUNZ Compiler. At a minimum, The Left Navigation Page provides users with a view of key Noun Types, and key controls that are tied to the context of the Web Page that the end user is viewing. Depending on the context of the page you're viewing, look to the Left Column Navigation Page in order to find similar controls or controls that support the view in context.
The software and documentation associated with the IF4IT NOUNZ compiler are a Copyright of the International Foundation for Information Technology (IF4IT), as of September 2010.
Note: NOUNZ is a registered trademark of the International Foundation for Information Technology (IF4IT).