Syntree Docs

A Word (Several Words) on Documentation

I have submitted three different forms of documentation accompanying the source code and implementation of Syntree. The first form is user targeted. It includes the FAQ & Help page of the Syntree website. User targeted documentation is intended for end users, and assumes only basic computer literacy. It does not contain documentation of the inner workings of the code, as it is assumed end users will not be interested in, nor assisted by, this information (at least, not in their capacity as end users). User targeted documentation is meant to be easily digestible and goal-focused -- that is, it should be geared towards assisting a user in completing certain tasks, these tasks being component tasks of the overall goal of drawing a tree. (For example, creating a node, drawing a movement arrow). The second form of documentation is developer targeted. It includes the README.rst files in some directories of the source code, as well as the JSDoc code docs. Developer targeted documentation is intended for those who wish to understand the inner workings of Syntree, or who wish to extend its functionality. It does not go into detail about how to accomplish end user tasks, nor about the purpose of Syntree as an application. It does go into detail about the structure and nature of the source code. The README files contain mostly information on the directory structure and identity of PHP and other files which make up the Syntree website, but do not contain detail on the objects, classes, methods, etc. which make up the application itself. This type of information can be found in the JSDoc generated code documentation. Developer targeted documentation is meant to be both goal-focused and asynchronously accessible -- that is, it should offer suggestions for potential developer tasks like creating a new type of graphical element, but should also provide extensive support for a developer searching for information on a specific entity (for example, the “select” function of the “ElementsManager” class). The third form of documentation is targeted largely towards the committee evaluating this project. It is the kind of documentation described by software engineering textbooks, and includes a class diagram, various sequence diagrams, a requirements list, several class and method analyses, and many use cases. This documentation is intended first and foremost as a demonstration of the creator’s ability to produce standards-compliant, organized, useful software engineering documentation. However, it will also be included with the developer targeted documentation, as it may aid any third party interested in understanding the structure of the application.