Software Engineering Handbook

The contents of this repository is used to dynamically build the Software Engineering Handbook site.

The main two data elements in this repository are:

• Authored content that is accessible to the end user from the handbook navigation tree
• Configuration data files to construct the handbook navigation tree

Contributors are invited to propose additions and improvements to any of these two elements following the contributing guidelines.

Structure of the Repository

Main Directories

software-engineering-handbook/
├──config/                                      main directory for the configuration files
├──Guides/                                      root of the authored contents for guides
├──Topics/                                      root of the authored contents for topics
└──Handbook/                                    handbook navigation tree. created automatically

All the authored content is placed under the Guides and Topics directories. All the configuration files are placed under the config directory. The resulting handbook navigation tree, which is created dynamically using the authored content and configuration files, is placed under the Handbook directory.

On the differences between the contents of Guides and Topics see their respective README files.

Comprehensive Structure

software-engineering-handbook/
├──about/                                       directory for contribution instructions
├──config/                                      main directory for the configuration files
|  ├──metadata/                                 metadata for the template file of navigation index.md files
|  |  ├──<metadata-configuration-yml-files>     metadata files with optional contents expected by the template
|  |  └──README.md                              metadata files description for contributors
|  ├──navigation/                               main navigation configuration folder for the handbook tree
|  |  ├──<navigation-configuration-yml-files>   handbook tree navigation configuration files starting from root.yml
|  |  └──README.md                              navigation configuration file description for contributors
|  └──templates/                                main folder for templates
|     └──index-template.j2                      Jinja2 template file for navigation index.md files
├──Guides/                                      root of the authored contents for guides
|  ├──<guides-subjects>/                        one or more folders for grouping subjects of related guides
|  |  └──<guides-markdown-files>                markdown files related to the parent guide subject
|  ├──index.md                                  "Internal Folder" message when rendered by GitHub Pages
|  └──README.md                                 policy and conventions for use on GitHub repository
├──Handbook/                                    handbook navigation tree. created automatically
|  ├──<first-level-handbook-subject>/           zero or more children folders for the hosting folder
|  |  ├──<second-level-handbook-subjects>/      zero or more children folders for the hosting folder
|  |  └──index.md                               current level index file with next level navigation links
|  └──index.md                                  root level index file with next level navigation links
├──images/                                      common media resources folder
├──Topics/                                      root of the authored contents for topics
|  ├──<topics-subjects>/                        one or more folders for grouping subjects of related topics
|  |  └──<topic-subject-index-markdown-file>    main index.md file for the parent topic subject
|  |  └──<guides-markdown-files>                sub-topics markdown files for the parent topic subject
|  ├──index.md                                  "Internal Folder" message when rendered by GitHub Pages
|  └──README.md                                 policy and conventions for use on GitHub repository
├──.madness.yml                                 default options and arguments for madness
├──_config.yml                                  Jekyll configuration
├──CNAME                                        canonical name record for the domain to be used by GitHub Pages
├──index.md                                     gets priority over README.md on GitHub Pages
└──README.md                                    this README file for contributors

Key Concepts and Principles

The Handbook directory hierarchy represents an instance of a handbook, which is created automatically based on the *.yml configuration files in config/navigation directory. The starting point for the navigation tree configuration is the root.yml file.

See the config/navigation README file for more information on the structure of the navigation configuration files.

The idea is to isolate the actual content of the handbook, given under Guides and Topics directories, from the navigation experience. This makes a robust and easily maintained repository, which supports relatively easy changes to the handbook structure and the navigation experiences.

The Handbook tree hierarchy includes directories and index.md files. All the directories under the Handbook directory have capitalized names with spaces ('Humanized' style), which represent the exact names of the Software Engineering Handbook chapters and sections.

All the directories of the Handbook tree have each an index.md file that is generated automatically when the Handbook tree is built. The index.md files include, among other optional parts, a contents list pointing to the children directories of the hosting directory (i.e., next level of the Handbook tree hierarchy). They also include optional references to guides and topics that are relevant to the handbook subject represented by the hosting directory.

See the config/metadata README file for more information on the structure of the navigation index.md files and on how they are composed automatically using metadata and Jinja2 template.

The entire content of the Handbook directory (i.e., directory hierarchy and all the index.md files) is automatically generated and maintained by the automation scripts in the tools repository, based on the configuration files under the config directory.

Note on the use of README.md and index.md files

README.md files are intended for contributors, while index.md files are intended for the end users visiting the Software Engineering Handbook site.

GitHub repository renders the README.md files by default. However, the index.md files get priority by GitHub Pages over neighboring README.md files.

---