The introduction to the architecture documentation lists the driving forces that software architects must consider in their decisions. This includes on the one hand the fulfillment of functional requirements of the stakeholders, on the other hand the fulfillment of or compliance with required constraints, always in consideration of the architecture goals.

Name
Introduction and Goals
Parent
Software Architecture Documentation
Iteration
Filled

Requirements Overview

Basic Usage

  1.  A user configures the location (directory and filename) of an HTML file
  2. and the corresponding images directory.

  3. HtmlSC performs various checks on the HTML and

  4. reports its results either on the console or as HTML report.

HtmlSC can run from the command line or as Gradle-plugin.

Terminology: What Can Go Wrong in HTML Files?

Apart from purely syntactical errors, many things can go wrong in html, especially with respect to hyperlinks, anchors and id’s - as those are often manually maintained.

  See BrokenCrossReferencesChecker.

Missing local resources: Referenced local resources (other than images) can be missing or misspelled.

See MissingLocalResourcesChecker.

See DuplicateLinkTargetsChecker.

Illegal links:: The links (aka anchors or URIs) can contain illegal characters or violate HTML link syntax.

See <<IllegalLinkChecker>>

See BrokenExternalLinksChecker.

Missing Alt Attribute in Image Tags: Images missing an alt-attribute.

Checking and reporting these errors and flaws is the central business requirement of HtmlSC.

Important terms (domain terms) of html sanity checking is documented in a (small) domain model.

General Functionality

Table 1. General Functionality
IDFunctionalityDescription
G-1
read HTML file

HtmlSC shall read a single (configurable) HTML file.

G-2
Gradle-plugin

HtmlSC can be run as Gradle-plugin.

G-3
command line usage

HtmlSC can be called from the command line with arguments and options.

G-4
configurable output

Output can be configured to console or file.

G-5
free and open source

All required dependencies shall be compliant to the CC-SA-4 licence.

G-6
available via public repositories, like bintray or jcenter.

G-7

Types of Sanity Checks

Table 2. Required Checks
IDCheckDescription
R-1
missing image files

Check all image tags if the referenced image files exist. See MissingImageFilesChecker.

R-2
broken internal links

Check all internal links from anchor-tags (href="XYZ") if the link targets "XYZ" are defined. See BrokenCrossReferencesChecker.

R-3
missing local files

Either other html-files, pdf’s or similar. See MissingLocalResourcesChecker.

R-4
duplicate link targets

Check all bookmark definitions (… id="XYZ") whether the id’s ("XYZ") are unique. See DuplicateLinkTargetsChecker.

R-5
Malformed links

Check all links for syntactical correctness.

R-6
missing alt-attribute

In image-tags. See MissingImgAltAttributeChecker.

R-7
unused-images

Check for files in image-directories that are not referenced by any of the HTML files in this run.

R-8
illegal link targets

Checks for malformed or illegal anchors (link targets).

Table 3. Optional Checks
IDCheckDescription
Opt-1
missing external images

Check externally referenced images for availability.

Opt-2
broken external links

Check external links for both syntax and availability.

Reporting and Output Requirements

Table 4. Reporting Requirements
IDRequirementDescription
Rep-1
various output formats

Checking output in plaintext and HTML.

Rep-2
output to stdout

HtmlSC can output results on stdout (the console).

Rep-3
configurable file output

HtmlSC can store results in file in configurable directories.

Quality Goals

Table 5. Quality Goals
PriorityQuality-GoalScenario
1
CorrectnessEvery broken internal link (crossreference) is found.
1
CorrectnessEvery missing local image is found.
2
SafetyContent of the files to be checked is never altered.
2
CorrectnessCorrectness of every checker is automatically tested for positive AND negative cases
2
CorrectnessEvery reporting format is tested: Reports must exactly reflect checking results.
2
Flexibilitymultiple checking algorithms, report formats and clients. At least Gradle, command-line and a graphical client have to be supported.
3
PerformanceCheck of 100kB html file performed under 10 secs (excluding gradle startup)

Stakeholders

Table 6. Stakeholder
RoleDescriptionGoal/IntentionType
aim42 contributor
contributes to aim42 methode-guide

check generated html code to ensure links and images are correct during (gradle-based) build process

role
arc42 user
uses the arc42 template for architecture documentation

wants a small but practical example of how to apply arc42.

role
Documentation author
writes documentation with Html output
wants to check that the resulting document contains good links, image references
role
software developer
creates software and needs provide documentation for it

wants an example of pragmatic architecture documentation and arc42 usage

role