Laying A Foundation
I've recently had some conversations with other developers about setting up and configuring projects.
I work 👷♂️ for a web development and marketing agency, WiredViews. Working for an agency involves a constant stream of greenfield projects, which means I've had lots of experience "starting" things.
Below I'd like to cover some recommendations for setting up a Kentico 12 MVC project and what benefits these bring.
This is going to be a 3-part post. In this post we're going to look at Documentation.
The previous post was about Developer Experience and the next will be about Configuration.
Let's begin!
Documentation
Documentation is not only commenting our code or a giant Microsoft Word file handed over to the client at the end of a project - it's also something that should live with the code to help us and our teammates long after we've forgotten how everything works (or if we're brand new to someone else's code 😓).
README.md
If you have worked with Wikis, Sharepoint, or Word and Text files passed around through email, you might be familiar with how documentation will often rot 💩 even faster than code.
That's likely to happen, because if developers aren't looking at it every day, they are sure to forget about it - we have more important things to do, like fixing all the bugs 🐛 we wrote last week 🤣!
This is why I recommend keeping documentation in the Git repository, the closer it is to code, the better chance it has to survive 👍🏿.
The GitHub convention of having a README.md Markdown file at the root of the repository is a great idea.
It gives developers a well known place to go for project configuration, setup, and deploying instructions. It can be versioned with the code and reviewed during Pull Requests 🧐.
If you're not familiar with writing a README.md file, checkout the Markdown cheatsheet or read about some good README conventions.
We can also use the README.md to link to other documents, or images in the repository, URLs of the application in different environments, specify what servers the app runs on, or add CI/CD badges to show the status of the build/deployment.
Now, with Kentico 12 MVC, we are managing 2 applications instead of 1. That means twice as many app settings, architectures, web servers, URLs, and quirks our teams need to know about to develop and build Kentico sites.
All of this knowledge needs a home that isn't in a single developer's head 💀, and a README.md serves that role well.
Here's a README.md template I like to use for my projects.
To improve the consistency and formatting of our markdown files we can use this Markdownlint VS Code extension 💪🏽.
If we want a better experience editing markdown files in Visual Studio, we can install the Markdown Editor extension 👏.
Diagrams
In the same way that the README.md is a 'living document', any additional documentation we create has the best chance to stay maintained if it is housed in application's Git repository.
This is especially true for diagrams, which can quickly get out of date!
We might try to keep these diagrams up to date by continuously re-exporting images from Visio or Draw.io, but that's a manual task and likely to be forgotten as soon as deadlines start to approach 🙄.
Wouldn't it be great if we could "code" up some diagrams and keep the code in source control! 😅?
Well, we can!
Mermaid, a JavaScript library that renders SVGs from a Markdown-like syntax and PlantUML, another similar syntax and set of tools, will let us do exactly what we want.
We can version and diff our diagram files, re-render images if we need to send someone an updated view, and have powerful visual representations of how our applications work for both stakeholders and developers, new (or returning) to the project.
I've used both tools and I think they're both cool. PlantUML is a bit more established, but Mermaid's toolchain might be a bit easier to get started with.
Want to be able to easily describe to teammates or stakeholders how a Kentico scheduled task integrates with that external system, or the way Kentico's cache system is integrated as a cross-cutting concern into your MVC application 😀?
Create a diagram! But create it with code and store that code in your repository 😁.
Edit: I just saw that Draw.io has a VS Code extension to allow for diagrams to be designed and saved (as XML) directly in our repositories!
General Documentation
Both the README.md and code-based diagrams are examples of specific documentation, but it's not uncommon to have more general purpose docs related to an application.
These could be meeting notes, commonly used .sql scripts, or instructions on how to perform tasks like grabbing the latest FTP drop that only needs to be performed every 6-months 😣.
These types of documentation can also be kept with our source code, especially if they are meant for the development team.
The README.md should usually be focused on high level information that's relevant to the entire code base.
Try creating a /docs folder at the root of your repository and saving everything there. It will bring the same benefits that were mentioned previously:
- Changes over time are visible in source control histories
- The whole team can review changes to documentation in Pull Requests
- Easy to find in a centralized location no matter which project (
/docs) - More likely to be maintained when close to to where developers work (code!)
In my previous post I discussed how all of these can be added as items to Solution Folders in Visual Studio:
CHANGELOGs
Projects change over time and each new change that makes its way out to QA or Production has the potential to impact users - hopefully in a positive way 🙂!
Stakeholders are likely keeping their own list of changes to the application - either for prioritizing work or messaging to the app's users.
Developers usually have much more technical knowledge of changes that happen with each deployment.
With Kentico 12 MVC projects, for the first time we have a Content Delivery application that is decoupled from the Web Forms CMS application.
This means that we can deploy updates to one of the applications without affecting the other, and we have more incentive to update our Production environment and deploy changes faster, since the Content Delivery (MVC) code base is smaller, faster, and decoupled from administration 😎.
It can be helpful to record these changes somewhere in the repository...
Literal CHANGELOG.md
The changes to an application over time can be documented in a CHANGELOG.md file kept at the root of a repository (a common practice on GitHub).
This makes it easy to see what the latest feature set was when looking at the history of this file, and also helps developers unfamiliar with a code base understand what a team has recently been working on.
I like the way that the Angular repository uses their CHANGELOG.md. It's very clear what was done for each version, which regressions were fixed and what new features were added. These changes each contain a link to a commit hash or issue, to let readers investigate further 🤓.
Meeting Notes
I've used lots of different tools for recording meeting notes related to Kentico sites I'm working on.
- Notepad
- Microsoft Word file attached to email (😒)
- Google Drive Docs
- Google Keep
- Pencil and paper
- Fresh VS Code session with a Markdown file
But a lot of times these documents get created and lost, or they are in a place that isn't easily reviewable by team members who might have ideas or questions (or maybe their own set of notes to add in).
Having a history of meeting notes in a repository, especially ones that impact how the application is coded and developed, can be beneficial for a team.
Using Markdown and an agreed upon folder/file naming structure can result in an easy to read history of the discussions around a project.
This thought leads me to my final recommendation on documentation...
Architecture Decision Record (ADR)
Have you ever started working in an established project and wondered "Why did the team choose to use .ini files for configuration 😤?" or "There is a bunch of JSON in this database column, why wasn't this de-normalized into multiple tables 🤔?" only to hear from a teammate "That was done a long time ago - I don't remember why 🤷🏼!"
With Kentico 12 MVC we are likely integrating even more external services (Azure Blob Storage, Azure Search), coming up with our own design patterns to organize the blank slate of a new MVC project, or using new tools like client side JavaScript frameworks, now that we have full control of the rendered markup from our sites.
One of the best ways to document architecture decisions made by team for an application is with Architecture Decisions Records (ADR) 🧐.
An ADR is exactly what it sounds like (as described by Steve Smith):
"An Architecture Decision Record is a tool for documenting a decisions that has been made (or is under discussion) related to the architecture of a particular system or application."
Each time your team decides to use Azure Blob Storage instead of the filesystem, rely exclusively on Guid values to reference database rows instead of auto-incrementing integers, or adopt Autofac as your dependency injection container after considering many others, you are making an architecture decision.
The motivation for discussion, what options were considered, and why the final choice was made, are great things for your team to record.
You can start an ADR (even in the middle of application development) with details as simple as:
- What technologies is the project currently using?
- Are there any risks/concerns with the current tech?
- What new design patterns or services have been discussed for adoption?
- Who is the expert/champion for each specific tech used in the application?
If you need help getting started on an ADR, checkout these templates on GitHub 💪🏾.
If anything, you might realize how little of the architecture of the application has been discussed before adoption and how much of the patterns and ideas are assumed to be 'common knowledge' on your team 😕.
Conclusion
In this post we looked at the many ways we can improve documentation in our Kentico 12 MVC projects. README files, diagrams, CHANGELOGs, meeting notes, and ADRs!
Whether or not we find any of these ideas is familiar will depend on how much we've worked on larger teams, contributed to open-source software, and developed more architecturally complex applications.
The benefit that each suggestion will bring to our project is also dependent on the goals of the project we are developing and the organization of people working on it 🤔.
However, no matter which documentation options we choose from those listed above, having some information organized and documented will always benefit at least 1 developer - ourselves, 12 months from now, when we've completely forgotten everything about the application and we have to fix a problem the CEO just found 🤦🏽♀️!
...
As always, thanks for reading 🙏!
We've put together a list over on Kentico's GitHub account of developer resources. Go check it out!
If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:
Or my Kentico blog series:
Latest comments (0)