-2

We have a webapp (ecommerce webapp) where we are currently working on. For some functions we wrote UML diagrams and ERD diagrams. We just made a high level architecture of the website. But the question is, for future proofness what type of documentation which describes the complete system will be best to write in this stadia? Creating a functional design or technical design? Write out all the functions we have and create UML diagrams for that? Purpose must be that there must be a source of reference + if our developer leaves the company that new developers can find there way through the documentation. But the question is: We are working backwards with documentation so to not waste to much time on documentation what would be best to write to get the best overview of the webapp

2

Different people value different kinds of documentation. For example, I don't find UML diagrams of a whole project helpful at all. Don't write huge documents that no one reads and that are difficult to maintain. Try to keep developer documentation as close to the code as possible.

The minimal amount of documentation is a README-style overview that describes how to test and deploy the project. Sometimes this is self-evident (e.g. if the language or ecosystem has strong conventions), but often it is not.

Also, consider providing a quick overview of the project structure – not necessarily on the level of classes, but on the level of directories. E.g. it might already be helpful to say “here are our templates, here are our controllers, over there our tests, here a library to integrate with our payment provider, and in here some miscellaneous helper functions.” An UML package diagram may or may not help for this. The point of this overview is to tell a new developer where to look.

Aside from an overview, it is helpful if implicit knowledge about the code base becomes explicit. E.g. functions might have various preconditions and guarantees. It helps to document that in the source code. You don't have to spend two weeks meticulously documenting every function. Instead, the boy scout rule might help: Leave a function better than you've found it. If you're working on a function anyway, you currently understand it's behavior. Take a minute to pour that understanding into a doc comment.

Finally, consider what happens if a developer quits or is let go. Ideally there is a contractually guaranteed notice period. While it may not be good to have this developer work on new features during their notice period, a great use of their remaining weeks can be to write docs. Notice periods can benefit both the company and the employee. If you live in a jurisdiction where they are not legally required anyway, consider negotiating contract amendments: while everyone is replaceable, having a bit more planability around that replacement can help you avoid the sudden loss of organizational knowledge.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.