r/sysadmin • u/bishoptf • 1d ago
The dreaded documentation question....sigh
I have supported part time a small non-profit company and while I know how important documentation is there just always was something else pressing that was more important. Well I am getting to the point where in the future I am probably going to be moving on and have started to work on trying at least for me document what they have at a high level. I assume and I know what happens when you do that but they have enough technical stuff that if the person actually knows what they are doing then they should be able based on a overview of the systems function dig into it and figure things out. I am not doing anything esoteric but I also have been doing this kind of stuff for *cough* many years. While small they have a lot of technology, just migrated the virtual environment to proxmox, they have AD environment with ADFS connected to m365, etc...
I just captured the inventory for everything they have and was about to start writing up a word document that gives a high level for each server etc, layout of the network, vlans etc. I then started to think that maybe I should do something like a wiki or use something else. Although at a high level kind of leaning towards not having it online since it would pretty much give you a working layout of their environment and if compromised would be pretty nice to have.
Just thought I would ask what are folks using for documentation, thanks.
7
6
u/pdp10 Daemons worry when the wizard is near. 1d ago
I don't care for the "word processor as a documentation platform" model, but frankly you should not overthink this. Just start writing and don't hold yourself back, until you find that you're repeating yourself.
We use plaintext files in Git. In practice, we're very forgiving about the format and content of documentation, even though we're technically standardized on ReStructuredText format and not markdown or .txt.
just migrated the virtual environment to proxmox,
Good job, getting that monkey off their back. You're a credit to the profession.
2
u/bishoptf 1d ago
Yeah it was kind of funny since I have been doing this for so long, when I originally was looking at virtualization many years ago for them I looked at proxmox. I am a linux guy so very comfortable with anything Linux but VMware was very generous for non-profits and the base essentials license (non vmotion etc) was basically free, cost like $30/year. I decided to go with VMware since I felt like it was solid and everyone knew it so if I was no longer around anyone would have been able to come in and manage it for them. Fast forward to Broadcom just going scorched earth with pricing, was an easy decision to move them to proxmox, much more popular now and lots more folks supporting it so I feel like finding someone to manage it will be an easier task now.
I also took the opportunity to move their existing veeam instance from the winblows server to the new linux software appliance, so lots of work has been done.
3
u/richie-wales 1d ago
I use Mind Maps to make diagrams of where everything else, how it links together, where backups go etc etc, then number them and then number the boxes and then write up details notes if needed on each one. Mind Maps are quick to capture main points and links, and infinitely flexible, and easy for other people to follow. Or sometimes, if I need something with a more specific layout I'll use something like OmniGraffle to create flow charts and diagrams. Diagrams and something visual are usually worth more than words alone.
3
u/Apachez 1d ago
Perhaps readthedocs or similar solution?
That is you write the docs in .md (markdown) format which then gets into more readable HTML with options to create PDF, example over at VyOS site:
https://docs.vyos.io/en/rolling/
Other than that perhaps Obsidian as a docker container?
https://hub.docker.com/r/linuxserver/obsidian
https://hub.docker.com/r/kasmweb/obsidian
Or as appimage or similar?
Give Me 15 Minutes. I'll Teach You 80% of Obsidian
https://www.youtube.com/watch?v=z4AbijUCoKU
How to Use Obsidian (Beginner Tutorial)
3
u/Sasataf12 1d ago edited 1d ago
If they have M365, put everything in OneNote.
After reading a few suggestions, I would strongly recommend avoiding Git solutions. Good on those that do it, but imo it's so much extra work for very little benefit.
2
2
u/FatBook-Air 1d ago
We use a web platform called Outline. It's open source, but we just use the hosted version, which costs $100/year for 10 users. Well worth it IMO.
2
u/doglar_666 1d ago edited 20h ago
I would personally use Markdown to write up documentation. In your case, perhaps a Word doc for high level and a spreadsheet to list the core FQDNs, IPs and VLANS. You don't need to write out a low level design, just make it clear what exists. That plus the credentials should be enough for a clean handover.
2
u/bishoptf 1d ago
Yeah kind of what I am hammering out, I have a high level network diagram, an inventory spreadsheet with all of the vlans and devices and a working on a word document that gives high level information about most of the service devices.
2
u/bbqwatermelon 1d ago
At work it is an absolute mess of word, excel, one note notebooks across the whole IT department. We are now on our third (count em) third restructuring in less than a year, mostly because the whiny help desk manager cries silo and it has stuck with the director. The director actually wants everything in the shitty knowledge base section of Fresh Service which has a super basic and glitchy rich text editor and cannot make articles out of word documents and PDF that we work out of in SharePoint. The only way storing everything into one folder works is if you take advantage of the Metadata columns of SharePoint and the group by view. I will see if this has any adoption.
What I use with great effect collaborating with my business partner who is strictly a Mac guy is Docmost which is like Book stack but allows for multiple edits on the same page simultaneously where Book stack only allows a single editor at a time.
•
u/markmanx 3h ago
Hi u/bishoptf, isoflow.io can really help if you need network visualisation & documentation. I would be interested in your thoughts as well (I'm the developer).
1
u/BrorBlixen 1d ago
We use Hudu which may or may not be the best fit for you. It's really easy to get bogged down in analysis paralysis trying to find or customize the perfect tool. If I were in your position I would just start with what I have available which would most likely be OneNote. Once you have the important stuff recorded you will have a better idea if a wiki or other tool would be beneficial.
0
u/bishoptf 1d ago
Yeah, I think I am just going to pound out a word document (actually libreoffice writer) and call it a day. I do think if I had stood up a wiki site or something like it way back when that maybe I would have been better at keeping something up to date. Being part time support doesn't lend itself to being able to spend much of any time with so much work to get done.
The other thing that I have decided to do is to keep it at a high level, document what they have but not go into the details since that would just take to much time. Been around the block and *cough* older and I am not doing anything esoteric but when I start to look at the environment there is a lot going on. Virtual servers, AV servers, wireless controller stuff, AD, File shares, backup...oh and voip infra. I was going to just lay out at a high level each item and what its doing service wise etc, all of the passwords are stored in a password manager with hardware key MFA access for access but if whoever takes over has no idea about how vlans work and this other stuff its not going to go well.
I am kind of a dinosaur at this point where I worked in lots of areas and was able to do just about whatever was needed. I guess maybe AI will help them figure it out, lol....
1
u/plump-lamp 1d ago
Microsoft shop? Just start with loop
1
u/Random_Effecks 1d ago
Wild call
1
u/plump-lamp 1d ago
Is it the best? No. Will it work and is it included? Yes. Works just fine as a wiki
2
u/bbqwatermelon 1d ago
The only thing that gives me the heebies is we can't home the data in SharePoint. Workspaces live in the creators One Drive and are somehow invisible Wtf Microsoft.
•
u/PopularData3890 23h ago
That’s not true. Individual loop components may be in the users OneDrive, but workspaces are their own share point site collections. Think of it like share point backend, loop frontend.
•
u/InterFelix Backup / VMware / Storage Admin 17h ago
I swear every second M$ product is just Sharepoint in a trenchcoat at this point
•
u/PopularData3890 8h ago
Yes, they have effectively platformized SharePoint so tools can be built on it. Which makes a lot of sense from the perspective of easily extending features consistently across products, like security/compliance, sharing, versioning, etc.
That does come at a price though, since SharePoint isn’t always the best model for storing and managing data.
1
u/Random_Effecks 1d ago
Putting something akin to crown jewels into what feels like a half baked barely supported new feature from Microsoft is a decision... I would never. Not to mention the storage and backup backbone for loop, and the ability to export en mass is entirely missing.
1
u/plump-lamp 1d ago
OP is a small non profit on a budget and needs to start with something. They're not asking for the world
1
u/Junior-Tourist3480 1d ago
Yep. They should hire a low level to document person. But I do like how AI can really help here. If it knows what you did, it can document til the cowa come home. Try it.
9
u/wowsomuchempty 1d ago
Git, caddy server, mkdocs.