aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlexander Kriegisch <Alexander@Kriegisch.name>2024-01-03 14:05:32 +0700
committerAlexander Kriegisch <Alexander@Kriegisch.name>2024-01-06 10:09:11 +0100
commitac71008e59b83d24ec5985e9e557c5cc6bd84c00 (patch)
treefba183f1dcd5aee3b7da79e5627631d8ba9b9ad0
parent4403dd934b17ecec6fee95906d0ffa3187759811 (diff)
downloadaspectj-ac71008e59b83d24ec5985e9e557c5cc6bd84c00.tar.gz
aspectj-ac71008e59b83d24ec5985e9e557c5cc6bd84c00.zip
Adjust design overview docs to other multi-page docs
- Link to other pages in index.adoc - Include other pages in design-overview.adoc Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
-rw-r--r--docs/developer/design-overview.adoc30
-rw-r--r--docs/developer/index.adoc8
2 files changed, 35 insertions, 3 deletions
diff --git a/docs/developer/design-overview.adoc b/docs/developer/design-overview.adoc
new file mode 100644
index 000000000..ee3bd755e
--- /dev/null
+++ b/docs/developer/design-overview.adoc
@@ -0,0 +1,30 @@
+= AspectJ Design Overview
+:doctype: book
+
+Here are some sobering words:
+
+"Although it is essential to upgrade software to prevent aging, changing software can cause a different form of
+aging. The designer of a piece of software usually had a simple concept in mind when writing the program. If the
+program is large, understanding the concept allows one to find those sections of the program that must be altered
+when an update or correction is needed. Understanding that concept also implies understanding the interfaces used
+within the system and between the system and its environment. Changes made by people who do not understand the
+original design concept almost always cause the structure of the program to degrade. Under those circumstances,
+changes will be inconsistent with the original concept; in fact, they will invalidate the original concept. Sometimes
+the damage is small, but often it is quite severe. After those changes, one must know both the original design rules
+and the newly introduced exceptions to the rules, to understand the product. After many such changes, the original
+designers no longer understand the product. Those who made the changes, never did. In other words, *nobody*
+understands the modified product." +
+ +
+Software that has been repeatedly modified (maintained) in this way becomes very expensive to update. Changes take
+longer and are more likely to introduce new 'bugs'."
+-- David Parnas on "Ignorant Surgery" in his paper on Software Aging
+
+////
+ATTENTION: Please do not remove blank lines in between 'include::' statements. Otherwise, section numbers in the
+table of contents (TOC) can be wrong and the first section of each document missing completely.
+////
+include::compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
+
+include::modules.adoc[Module Structure]
+
+include::language.adoc[Language Design]
diff --git a/docs/developer/index.adoc b/docs/developer/index.adoc
index aa347182e..a358948b3 100644
--- a/docs/developer/index.adoc
+++ b/docs/developer/index.adoc
@@ -19,6 +19,8 @@ Software that has been repeatedly modified (maintained) in this way becomes very
longer and are more likely to introduce new 'bugs'."
-- David Parnas on "Ignorant Surgery" in his paper on Software Aging
-include::compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
-include::modules.adoc[Module Structure]
-include::language.adoc[Language Design]
+**Table of Contents**
+
+* xref:compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
+* xref:modules.adoc[Module Structure]
+* xref:language.adoc[Language Design]