I’m looking for a “best practice” or “advice” on something.
I’m a member of a 7 person SQL Server team. Like SQL Server, our team has many specialties such as a person, a database engine person, a patching person, a replication person and a disaster recovery person. We can all do parts of each others work, but at the end of the day someone on the team always knows something a lot better than someone else. Since our team is diverse, we document things as much as possible so that others can pick off where someone left off.
I’m the guy on the team that is making Octopus “projects” to handle our different deployment needs. Patching, database backup and restores, Visual Studio project deployments like DACPAC/SSRS/SSIS/SSAS, etc. I’ve noticed is that our projects can have 10-15 steps and each step is hopefully just a bite size of a bigger picture so that we can debug and resolve problems. To that end, the projects should have steps that are commented upon inside the step, when available in like a script step. Each step has a bunch of dependencies, like the creation of a variable set, or a NuGet package that its connected to, or a role, an environment, a channel, a local variable, etc that is in place to make the project flow properly.
My question therefore is about how to document each project. If I leave each project as “self documenting” in Octopus, then I can be exposed to a problem if that Octopus Server was wiped out, I’d have no record and documentation on the project. At the same time, putting all of the minor script clippings in a word document seems incomplete or messy because there are so many things that can be in a step.
So how do you all document your projects? Do you have methods you use that checks in a project in TFS or something? Does it work well? Have you ever felt the pain of not having projects documented elsewhere?
Thanks for getting in touch and it’s a great question. I’ve heard of a few different ways that people document their Octopus process and I’d recommend something like the following.
Using the Octopus Manager, you can export and import your Octopus settings/dataset to a directory. The output of the export is a simple folder structure with text files (JSON) and it can easily be stored in source control. Exports can be updated in source control regularly which can help monitor them for changes. Finally, these backups can then be imported again if something happens to the server.
Document the high level process of what happens in each project and it’s steps and store it somewhere (text file, word document, wiki or intranet) so the rest of your team can access it. Personally, I’m a fan of wikis because they’re quick and easy to update but it really comes down to what works for you and your team.
Thanks for your reply… You just inspired an idea. If Octopus was born out of a desire to help .NET developers, why not have someone try this…
Create a custom project type for Visual Studio for Octopus Projects that incorporate these json files.
That would allow a GUI that can easily and ready be documented, it would allow us to integrate them with our source control tools, and more closely align our Octopus projects with our work.
I wish I had those skills, I’m more of a DBA/BI Developer, but I think this idea could work, thoughts?
Thanks for the reply. This is a very interesting idea/suggestion. We have talked about improving the import/export experience but we don’t have any concrete plans at the moment. I’ll share your idea with the rest of the team but if you’re keen, you could always add it as a suggestion to our user voice site https://octopusdeploy.uservoice.com/. We regularly review the suggestions and are aware of those that gain the most community support.
