Advice for building documentation for a small company?
Advice for building documentation for a small company?
Hi guys, I recently started working at a company with about 50 people that has grown to large for their current IT setup. They have no documentation or any SOPs. Has anyone been in a similar situation and how did you go about creating documentation, especially when you are new and don't fully understand all of the services they have in place?
Thankfully it's mostly a Microsoft shop and pretty low tech but there are dozens of exchange rules in place that no one knows why they exist or what they do, dozens of SharePoint sites with critical information strewn about them and so on. It's hard to think where to even start and decide what the best way to organize this information will be, and keep in a place a system where we will update it regularly. Any advice would be greatly appreciated.
One thing that worked for me in a similar situation was to enforce an "owner" tag or some kind of registry on everything.
Basically, if you set something up, change some configuration, whatever - put your email address on it.
Write a readme.md or wiki or guide too, but at the very minimum put your name down as the owner so that when someone comes along and wants to know if it's safe to change/upgrade/delete, they can find you and ask. If someone leaves, you can do a quick search and get them to handover/write up anything they were responsible for.
This will be important as the company gets larger - don't put your personal (or anyone's) email address on it. Put a department DL or Teams Group email on it, unless you alone want to be the only supporter and owner of whatever it is until you leave the company.
This is already a huge problem for me. A lot of accounts have the names of former IT admins that left 5 years ago and no one has bothered to update contact info with some of our suppliers. We are getting better at it now but I'm still finding more accounts that no one seems to know we have.
Personally, I think the biggest challenge with documentation is keeping it up to date.
The only way I've found to be actually up-to-date on docs is to do GitOps and have self-documenting code. That way every change being made is automatically documented with a commit message.
If you can't do that because your tools aren't GitOps compatible, you need management to enforce some kind of documentation rule. Like every time a system gets touched, documentation needs to be updated. A project isn't complete until docs are done/updated.
This is easily said, but in practice it's just not going to happen. You need a team that both actually wants to this, and has the time to do it.
On top of schnapsidee's already correct feedback, if the company is willing to enforce documentation deliverables (which it really should), I've found it important to have a minimal documentation deliverable formulated. Don't immediately overshoot with all the different types and subjects, but find a set of documentation aspects that are agreeable by the company at large as a minimum. You can always increase this later, but it's hard to set the bar too high immediately as that removes any willingness from the organization as well.
You also can't just 'reset' the organization and suddenly do things in a different way. It will need to be evolved into a better documentation structure. Perhaps you could start with just a portal that points to the various existing documentation libraries and services. That can help you identify what types of documentation you have, and perhaps even find a good grouping. Also, try to see what information should be protected (don't want to have passwords laying around, or other risky information) versus which information should be easily accessible.
Many things will have a description or notes field — such as AD accounts, Exchange rules, SharePoint sites, and the like. Sometimes it’s visible to the user, and sometimes not. Always try to write something in there. That’s a great start.
I'm partial to infrastructure as code techniques as a way of writing things down and tracking changes, but that's obviously not always possible in corporate IT with "edge computing".
If you're documenting something related to code or a specific computer, I think readme .md files are the best, because you can't lose them.
If you're writing pure documentation, there are really nice markdown site generators like docusaurus, but if you're just making internal documentation, you can just file everything with an online cloud documentation tool like Notion or even Google Docs. If you want online documents like Google docs, but you don't want Google to have all your secrets, you can run your own corporate Nextcloud server, which is very common in Europe.
With things like Exchange rules, I wonder if people thought they were self-documenting? Like, our puppet manifests don't have separate documentation for them. For other things, we use a wiki for everything, and it is mixed success. People who know have to think it's something that someone else would need info about it to then write that info down. We often try and separate out "this is the high level goal" from the minutiae of doing it. And this could be a big problem if lots of people leave.
Honestly, anything is better than nothing. Write whatever you think is relevant and eventually you'll get a feel for formats that work for your company.
We use internal wiki, it works reasonably well. The problem is keeping the information updated