| Creating technical Documentation | ||||||||||||||||||||||||||||||||||||||||||||||
| The basic challenge | Identifying and understanding the present processes of an undocumented software system: Kinepict Medical Imaging Tool by reengineering. |
|||||||||||||||||||||||||||||||||||||||||||||
| How to reengineer undocumented software systems ? | There are well-proven software systems reengineering methods
|
|||||||||||||||||||||||||||||||||||||||||||||
| Current State | Anarchy is the result of complete absence of any technical documentation (excluded the source code and some sporadic test result). This results in individuals and units in an organization managing their own information resources and developing information reports that serve their own needs rather than the needs of the organization as a whole. |
|||||||||||||||||||||||||||||||||||||||||||||
| What we need... | Maximizing the following four attributes of information values:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Terminology | The terms used are summarized in this section to ensure the needful unambigousness of terminology. |
|||||||||||||||||||||||||||||||||||||||||||||
| Documents have to be created | The following types of documentations is an absolutely minimal set to be proficient producing qualified software product. They would provide an entry level to an efficient production of sophisticated software products
|
|||||||||||||||||||||||||||||||||||||||||||||
| Form of presentation | The interrelations between these document types are depicted in Entity-relationship (ERD) diagrams. |
|||||||||||||||||||||||||||||||||||||||||||||
| Types of Requirements | Several other levels of requirements can also be defined (subsystem-, component-, subcomponent-level). Accomplising a minimal technical documentation set these two levels of requirements seems to be enough. The requirements can be divided into two, mostly disjunct groups: these are the Stakeholder Requirements, and the System Requirements. Using ERD diagram, that implicates two one-to-N relations, as can be seen below:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Requirement and High-Level Design | The High-Level Document (HLD) gives functional classification over the whole system, and it is based on the full set of the requirements. The HLD implementation can be a simple SysML block diagram, composed of maximum 10..12 entities. It is a one-to-one relation:
|
|||||||||||||||||||||||||||||||||||||||||||||
| High- and Low-Level Design | The Low-Level Design (LLD) is a result of a step-by-step refinement design process: the LLD gives a higher resolution about the building blocks of the HLD. Concerning the volume of the LLD it is no more than 3..4 A4 pages per building blocks of the HLD. The simple ERD diagram detail shows the one-to-N relation between HLD and LLD:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Low-Level Design and Implementation | The resolution of the LLD design entities is fine enough to take them as direct input for the implementation. The software implementation means constructing Java classes. The LLD design entities have a one-to-one relation to the Java classes:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Design Documents and Implementation | Assembling the previous four ERD diagram details, we can see the relations between the design documents, the requirements and the implementation entities:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Adding Test Cases | Each requirement must be tested not only on the highest level of the design documents (as counterparts of the requirements), but on the LLD-level, as well. The Test Cases (TCs) can be groupped into Test Case Lists (TCLs), as can be seen on the following ERD detail:
|
|||||||||||||||||||||||||||||||||||||||||||||
| The Big Picture | Compounding the previous ERD fragments we can see each relation between the
Because of the format of the design documents and the requirements can easily be transformed to HTML (e.g. from DITA) and the source code documentation can also be presented in HTML format, the required relations can easily be realised by HTML-links:
|
|||||||||||||||||||||||||||||||||||||||||||||
| Volume, Format, Effort |
|
|||||||||||||||||||||||||||||||||||||||||||||
| References | This section contains recommended documents for basic and advanced level of systems engineering, document handling and skills required by management of software development processes. The referred documents are lawful copies (not pirated, obtained legally), they can be downloaded as well. |
|||||||||||||||||||||||||||||||||||||||||||||
| Terminology | |
| DITA | DITA is an XML-based open standard for structuring, developing, managing, and publishing content. The figure bellow shows a requirement (and its several attributes) written in DITA and its XML-source, as well:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="SH_M_F_grapeVineDiseases">
<title>Grapevine Pathogens and Pests</title>
<prolog>
<metadata>
<keywords>
<indexterm>grapevine pathogens</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<section>
<p><b>Requirement Identifier</b> SH_M_F_grapeVineDiseases </p>
</section>
<section>
<p><b>Name:</b> Grape Vine Pathogens and Pests</p>
<p><b>Text:</b> The <xref keyref="_plantCT" format="dita"/>
shall provide warning
information about the infection probability regarding to the following
pathogens: <sl>
<sli>Grapevine powdery mildew (Erysiphe necator)</sli>
<sli>Grapevine downy mildew (Plasmopara viticola)</sli>
<sli>Grey Mould (Botrytis cinerea)</sli>
<sli>Phomopsis cane and leaf spot of Grapevine (Phomopsis viticola)
</sli>
<sli>Grape black rot (Guignardia bidwellii)</sli>
</sl> and pests (<xref keyref="_nematodes" format="dita"/>,
<xref keyref="_molluscs"
format="dita"/>, <xref keyref="_insects" format="dita"/>, and <xref
keyref="_acari" format="dita"/>): <sl>
<sli>Grapevine berry moth (Lobesia botrana)</sli>
<sli>European grape berry moth (Eupoecilia ambiguella)</sli>
<sli>Grape bud mite (Colomerus vitis)</sli>
<sli>Grape rust mite (Calepitrimerus vitis) </sli>
</sl></p>
<p><b>Rationale:</b> These are the main pathogens that affect
grapevines. They can actually halve the harvest prospects.</p>
<p><b>Level | Type | Subtype:</b> Stakeholder Requirement |
Mandatory | Functional Requirement </p>
<p><b>Source:</b> This confirmed and verified observation is part of
the vineyardist praxis (Hlaszny dr., Edit) </p>
<p><b>Creation Date:</b> 2016/02/13 13:51</p>
<p><b>Importance:</b> 10 of 10</p>
<p><b>Verification/Validation Method:</b> by scientific
literature</p>
<p><b>Verification/Validation Status:</b> not yet in progress</p>
<p><b>Note:</b> n/a</p>
<p><b>See Also:</b>
<sl>
<sli><xref href="../generaOfPlants.dita">Genera of
Plants</xref></sli>
</sl>
</p>
</section>
</body>
</topic>
|
| Entity-relationship model | An entity may be defined as a thing capable of an independent existence that can be uniquely identified. An entity is an abstraction from the complexities of a domain. An entity-relationship diagram (ERD) shows the relationships of entities in form of a special block diagram, where connecting solid lines show the relationships of the entities. Cardinalities (1 : 1, or 1 : N) specify how many instances of an entity relate to one instance of another entity.
|
| Feature | A Feature is a small, granular function or characteristic expressed in client-valued terms as a satisfaction of a requirement. |
| Features List | A list of features. |
| High-level design | High-level design (HLD) explains the architecture that would be used for developing a software product. The architecture diagram provides an overview of an entire system, identifying the main components that would be developed for the product and their interfaces. The HLD uses possibly nontechnical to mildly technical terms that should be understandable to the administrators of the system. |
| Low-level design | Low-level design (LLD) is a component-level design process that follows a step-by-step refinement process. This process can be used for designing data structures, required software architecture, source code and ultimately, performance algorithms. Overall, the data organization may be defined during requirement analysis and then refined during data design work. |
| Product Sheet | A product sheet or also known as data sheet is a type of short document that contains a summary of the performance and other various technical features of a certain item or product, machinery, subsystem, materials, and other components. |
| Reengineering | Product reengineering is the examination, study, capture, and modification of the internal mechanisms or functionality of an existing product in order to reconstitute it in a new form and with new functional and nonfunctional features, often to take advantage of newly emerged technologies, but without major change to the inherent purpose of the product. |
| Requirement | A requirement is a statement that identifies a product or processes operational, functional, or design characteristic or constraint, which is unambiguous, testable, or measurable and necessary for product or process acceptability. |
| Stakeholder requirement | The stakeholders include all the people, organisations, and institutions that are part of the systems environment because the system provides benefit to them and they have an interest in the system. The stakeholder requirements provide a concise, non-technical description of what is being developed at a level that is accessible to senior management. |
| SysML | The SysML (Systems Modeling Language) is a general-purpose modeling language that supports the specification, design, analysis, and verification of systems. These systems may include hardware, software, data, personnel, procedures, and facilities. SysML is a graphical modeling language with a semantic foundation for representing requirements, behavior, structure, and properties of the system and its components. The modeling language is intended to model systems from a broad range of industry domains such as software, aerospace, automotive, health care, and so on. |
| System requirement | A system is an integrated composite of people, products, and processes that provide a capability to satisfy a stated need or objective. System requirements are all of the requirements at the system level that describe the functions which the system as a whole should fulfill to satisfy the stakeholder needs and requirements, and is expressed in an appropriate combination of textual statements, views, and non-functional requirements; the latter expressing the levels of safety, security, reliability, etc., that will be necessary. The system requirements
|
| Test Case | A test case is a specification of the inputs, execution conditions, testing procedure, and expected results that define a single test to be executed to achieve a particular software testing objective, such as to exercise a particular program path or to verify compliance with a specific requirement. A minimal set of Test Case attributes |
| Test Case List | List of Test Cases. |
| Use Case | A Use Case defines the interaction a user has with the system in order to satisfy one or more Requirements. Features also have relationships with Use Cases. The Feature identifies the facility that provides the means for that interaction. |
| References | |
| Documentation | Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald, Eric Radzinski: The IBM Style Guide: Conventions for Deployment and Advanced Writers and Editors. IBM Press, 2012. ISBN-13: 978-0-13-210130-1. Available in PDF format. Michelle Carey, Moira McFadden Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, Elizabeth Wilde: Developing Quality Technical Information. IBM Press, 2012. ISBN-13: 978-0-13-311897-1. Available in PDF format. Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt: DITA Best Practices. A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press, 2012. ISBN-13: 978-0-13-248052-9. Available in PDF format. |
| SysML |
Sanford Friedenthal, Alan Moore, Rick Steiner: A Practical Guide to SysML – The Systems Modeling Language, 2008, Elsevier Inc., ISBN 978-0-12-374379-4. Available in PDF format, e-book-ISBN: 978-3-446-43127-0. as well. Oliver Alt: Modellbasierte Systementwicklung mit SysML, 2012 Carl Hanser Verlag, e-book-ISBN: 978-3-446-43127-0 Available in PDF format, as well. |
| Systems Engineering | Andrew P. Sage, William B. Rouse: Handbook of Systems Engineering and Management 2nd Edition, Wiley-Interscience, 31 Dec. 2014 | 1504 pages | ISBN-13: 978-0470083536 Available in PDF format. Alexander Kossiakoff, William N. Sweet, Samuel J. Seymour, Steven M. Biemer: Systems Engineering Principles and Practice, John Wiley & Sons, Inc. 2011, ePDF ISBN: 9781118001011. Available in PDF format. Guide to the Systems Engineering Body of Knowledge (SEBoK) version 1.9.1. 16 October 2018. Available in PDF format. |