The client is a global telecommunications giant with operations across 5 continents.
The client had an application that was used to manage one part of its mobile operations. This application is being updated constantly to meet emerging regulatory and business requirements.
However, the client had minimal system and technical documentation for the system. As a result, when new members joined the development team, they found it difficult to understand the huge codebase as well as the relationships between the Oracle tables and Apache Hadoop HDFS.
In addition, the business objectives, business rules, and the system architecture had not been updated and this compounded the problem of training new team members.
The client was finding that their time-to-market was suffering because the application could not be updated quickly.
The client then approached ibruk Consulting to complete the end-to-end system and technical documentation for the application.
At the very outset, the client clearly stated that they would not be able to handhold us or give us much support. Of course, the client team would explain the functionality of the application and give us complete access to the code and databases. However, beyond that, the ibruk technical writing team would have to work independently.
Result of the Analysis
ibruk Consulting started the project with an analysis of the available code and code documentation as well the database systems and the associated documentation. We found that the web application had well-written JAVA code base and used a Model View Controller (MVC) architecture. At the backend was a robust database system based to Oracle and Apache Hadoop Distributed File System (HDFS).
As the ibruk Consulting technical writing team were determining the scope of the system and technical documentation needed, it found that we needed to create and/or update almost all the system and technical documentation associated with the system.
Over a period of 6 months, a 4-member dedicated technical writing team—proficient in Java, UML, Database Design, and SQL—worked independently to create:
- System Specification Document that covers:
- Business objectives
- Business rules
- System architecture/High-level design
- UML diagrams such as Use Case, Sequence, Class, and Component diagrams
- Database Design Documents that covers:
- Conceptual design
- Logical design
- Physical design
- Data access rules
- Other details such as naming conventions, etc. (if required)
- User Interaction Documents that include:
- Screen shots/Wire frames
- Database connections
- Code Documentation that covers:
- Description of the functionality
- Function signatures, input and output parameters
- Input and output tables
- Examples of use
For the code documentation, the ibruk technical writing team used Javadoc via the Eclipse IDE.
The situation with depicting database design was a bit tricky since we needed to describe the relationships between over 100 entities in Oracle and HDFS. We used Microsoft Visio to create Entity Relationship (ER) diagrams.
We used Microsoft Visio for the detailed System Architecture diagram as well.
For UML diagrams, Modelio proved to be an effective tool.
- The client now has comprehensive system and technical documentation for the application.
- The documentation is structured and written such that the client’s development team can update it without help from the ibruk Consulting technical writing team. This will help the development team easily maintain the documentation and keep it current with the application.
- The client was able to train and induct new developers quickly. This has significantly improved the client’s ability to scale up the development team and reduced the time-to-market.