When applicable, a careful demarcation between the functionality of this package and others which - at least superficially - appear to address the same requirements.
- Note: it's entirely possible that a discussion of what a package + Note: it's entirely possible that a discussion of what a package is not intended to do differs from a discussion of future improvements for the package.
@@ -51,7 +51,7 @@ team needs to be ready for inquiries regarding features our software lacks.
Note that such a discussion may differ from a discussion of a - package's potential future improvements. + package's potential future improvements.
No single design solution can optimize every desirable software attribute. For example, an increase in the security of a system will @@ -63,7 +63,7 @@ chosen, and the reasons for your choices. Some areas of importance to keep in mind are:
Areas of interest to users:
Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability
Areas of interest to developers:
Maintainability
Portability
Reusability
Testability
- Here's where you discuss the abstractions used by your package, such + Here's where you discuss the abstractions used by your package, such as the procedures encapsulating the legal transactions on the data model. Explain the organization of procedures and their particulars (detail above and beyond what is documented in the @@ -75,7 +75,7 @@ Remember that the correctness, completeness, and stability of the API and interface are what experienced members of our audience are looking for. This is a cultural shift for us at aD (as of mid-year 2000), in - that we've previously always looked at the data models as key, and + that we've previously always looked at the data models as key, and seldom spent much effort on the API (e.g. putting raw SQL in pages to handle transactions, instead of encapsulating them via procedures). Experience has taught us that we need to focus on the API for @@ -102,8 +102,8 @@ you can organize by the expected classes of users. These may include:
Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users
You may want to include page mockups, site-maps, or other visual aids. - Ideally this section is informed by some prototyping you've done, to - establish the package's usability with the client and other interested + Ideally this section is informed by some prototyping you've done, to + establish the package's usability with the client and other interested parties.
Note: In order that developer documentation be uniform across @@ -112,7 +112,7 @@ respectively.
Finally, note that as our templating system becomes more entrenched - within the OpenACS, this section's details are likely to shift from UI + within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics.
Under OpenACS 5.9.0, parameters are set at two levels: at the global level by @@ -126,8 +126,8 @@ Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this section.
- Although a system's data model file often contains this information, - this isn't always the case. Furthermore, data model files often + Although a system's data model file often contains this information, + this isn't always the case. Furthermore, data model files often undergo substantial revision, making it difficult to track down the system creator. An additional complication: package documentation may be authored by people not directly involved in coding. Thus to avoid