The Technical Solution

The Solution to Software Documentation is a Software Representation Layer

  • Software                                                          the actual Software
  • Software Representation Layer                  a logical representation of the actual software
  • Documentation                                               documentation "about" the actual software
     

Only App Overview provides a solution to Software Documentation, because it creates a layer for documenting your Software between your Software and the Software Documentation.

All attempts to document Software have failed for one reason, and that is they do not provide the structural foundation that allows Software Teams to capture a representation of their software.

To capture documentation “about” your Software, you have to first be able to create a representation of the Software, and only then should you add the documentation to the specific items within the representation.  The Software world has been waiting over 50 years for this solution!

The representation serves two main purposes: 

  1. It forces the unique artifacts within your Software System to be represented with a unique ID, thereby allowing documentation to be attached precisely where it needs to go, in one single place, and easily found at a later time
  2. The representation creates a way to (virtually) navigate your Software

Since Software development tools and IDEs do not provide a way to navigate and explore your Software across different tiers, technologies and systems, a representation layer allows a comprehensive view of all layers and tiers in one place, connecting all of your Software documentation together as a seamless experience.

 

The Software Domain, and the Software Documentation Domain

Before taking a deeper dive into how the Software Representation Layer solves the requirements of a viable Software Documentation Solution, these two terms should be explained:  the Software domain, and the Software Documentation Domain.

The foundation of any viable Software Documentation solution must allow information to be captured in two domains:

  1. the Software Domain
  2. the Software Documentation Domain

The Software Domain is a representation of the Software itself.  For example, a hypothetical Software System has object A, artifact B, and module Z, etc., as well as relationships among them, logical groupings, interdependencies, processes, file locations, hierarchies, and on and on. These “things” must first be captured and represented in your software documentation solution.  The Software Domain must be capable of capturing both the physical structure of your software, as well as various logical views of your Software.  Only when you have that in place, do you have the correct foundation laid for the Software Documentation Domain.

The Software Documentation Domain is a collection of the documentation “about” anything in the Software Domain.  The Software Domain is comprised of “points” or “unique id’s” that represent “areas” of your Software you want to document.  Since the Software Domain captures the physical objects, relationships, and abstracted views of your Software, you then have a single, appropriate place to add your documentation.  This is the only way a Software Documentation Solution can work; documentation about your Software needs to be in the closest relative proximity to the software context or area you are trying to document.  This allows the user experience to be as intuitive as possible.

 

 

 

All rights reserved. Your business name.

© 2019