Creating Great Documentation(and code) for your software project

I’m going to discuss some tools and techniques for creating really fantastic developer documentation for your software products. The goal is to greatly improve the quality of your software as well as increasing your overall productivity.

It is hard to create really comprehensive documentation for a software product but comprehensive documentation makes a massive difference in allowing other developers access to your software and to understand what is going on with your software.

So what are some of the attributes of really comprehensive documentation

  • The software is easier to understand
  • It is easy to find the answers you’re after
  • It is easy to navigate the software architecture and understand how everything works together
  • The documentation should be highly available
  • It is up to date

I really believe that all comprehensive documentation and excellent software starts with a detailed design. So the first thing that we need to do is create the design and use that design to create the comprehensive documentation. Sounds simple but not many companies do this well.

Firstly let’s look at some of the common problems that stop people from creating comprehensive documentation and then we will look at now SilverModel solves these issues

Some of the common problems are:

  • Documentation is out of sync with the design of the project
  • There is no documentation
  • There is no documentation in the code
  • Documentation Tools don’t integrate with development tools

While I have worked on many projects for many companies I cannot recall a single one that actually had comprehensive documentation for the products internally! In fact, most had none or what they had was quickly abandoned! This has been a huge cause of lost productivity as the only way developers have to work out what is happening in a project is to dig through the code.

The main cause of this documentation crisis has been poor tools since the design specifications(often written using Microsoft Word) have no direct link to the software being created. Leading to new features etc been built directly into the code and not updating the design specifications.

So what happens if the design specification can create the code!! This is what SilverModel does.

Now by designing and documenting the software in SilverModel this also allows at the same time the generation the code for the software! While maybe not all the code required will be created, enough will be created that along with the documentation created will allow for massive productivity gains for developers. This is a game changer! My goal with SilverModel is to get as close to 100% for turning the design into code than I can. Then developers can focus on solving the interesting problems and not writing infrastructure code.

With a short time spent in designing(think minutes to hours) and documenting your project, it is possible to create 1000’s to 10’000 of lines of code!!!! Which is truly a huge increase in developer productivity.

Creating Documentation with SilverModel

When creating a design we need the documentation to be made highly available. So that the developers can easily access the information and be highly productive. Digging through the code to find an answer is not productive so the documentation should be made available at the following locations.

  • In a website or wiki
  • As inline code comments
  • As a Word document (if the website is not available)

SilverModel can create all of the above. This will massively improve the overall quality of your projects as well as increasing your productivity.

I will use the Todo sample app to show how you can document a project(and create the code do).  See the source code on Github and this post on the ToDo sample app.

Even in a simple app like this, it is not always obvious what all the classes and properties do. As individual developers could have their own interpretation of what should be happening which will only lead to confusion and wasted time in a project.

SilverModel allows for the creation of rich documentation for each element in the Class Diagram e.g. Classes and Properties

Documentation Editor

The documentation for each element can hold

  • Text
  • Formatting e.g. Bold, Font Size, Colors etc
  • Pictures

The documentation editor has most of the features of Word Processor with the added advantage that the documentation is now directly linked to the design!

Sample: Screenshot showing documentation for the User Class

 

Metadata Collection

Another important way of collecting documentation is via Metadata which is available for all the elements in your design.

Each element also has a “Description” property which can be used to describe the current element.

Also when each element within the design has had metadata assigned to it by the code generators, this becomes part of your documentation.

You can use the metadata to collect information and document anything you require, so for example

  • Database Primary Keys
  • Regular Expression Valuation patterns
  • Form Design Layout
  • etc

Sample: Screenshot of the property Title with metadata for Form design and database information.

In the above example, not only have we documented where the field “Title” should appear in a form(web or mobile).We have can also use this documentation to generate the code that will display that property at that location on a form!

See the Todo app on Github for another example of this in action

 

Creating Documentation in code.

During code generation, SilverModel allows for the documentation created during the design to be injected into the code.

This has two benefits, first, during development, the developer can quickly understand the code by viewing the injected documentation and secondly it allows allow the IDE to display richer tips to the developer.

Example of a code generator that injects the “Description” metadata documentation into the code

Creating Documentation as a Website

SilverModel also includes a code generator called “Website Documentation” that creates a website to document your current project. Click here to see the code generator source code.

See blog post for more detailed information on creating documentation via code generation.

Also, the Todo app on Github has the full documentation website generated for it.

Summary

SilverModel can make a massive difference to your productivity by making your designs and documentation easily accessible. Also, SilverModel can turn your designs and documentation into code saving you weeks to months of development effort.

All our code generators and sample apps are available on Github for you to download and modify. If you have any questions please contact us and we will be happy to help.