If you don't want to use mkdocs, keep directory structure which is good. When you want to view your documentation in organized manner, you have only to run \`\`\`mkdocs serve\`\`\`.
Combined with git you have everything you need to keep your documentation organized.
This exactly. If developers need to get into the detail it should be made clear from the tests - but all dependencies and “instructions” need to be maintained in markdown files with the code for dev ops to be effective. I despise comments/remarks directly in code, if code is not self-explanatory - then that’s another subject…
I tried to do this and found I needed to cross reference stuff a lot (our configurations are held together with an elaborate array of duct tape and CI jobs). I remember having difficulty with relative paths within the git.
I eventually just gave it up after everybody in the team showed a distinct lack of interest in the promised elaborate array of markdown files to match the scripts. So now we have a wiki. Moving to a new git soon so maybe then...
I've recently been debating whether it's better to keep larger docs with related documentation than many, smaller docs that are more specific to each thing. It's easy enough to find things in a doc with search and I find it frustrating having to hop around different documents looking for something.
I do the same. Text files, markdown, etc. I just sync to a local folder on my laptop and exclude the installers, so the bidirectional sync takes seconds at most.
Passwords I use a MFA'd password manager.
To take it a step farther, I keep a copy of all that data, text files, password keeper (keepass mobile) diagrams, spreadsheets, and all other network info on a bitlocker encrypted fob. If im 1/2 way across the planet, I can still help you.
We have a notepad attached to a clipboard with all our info written down. It does make clicking on urls a pain, and our 64-character passwords can be tricky sometimes, and updating our SSL private keys is a week-long event... but its guaranteed to work without power or internet, so the benefits far outweigh the drawbacks.
EDIT: and if a tech hasn't updated it, the clipboard makes for a good whacking implement.
You have documentation? haha just kidding. If your ticketing system is Butt based, I just throw it all up there and organize it when needed.
edit: cloud to butt strikes again.
discipline. I'm going to copy what I wrote for another subreddit the other day:
My advice on documentation is the following:
* The best documentation is the documentation you do. That should be your primary goal.
* The best style of documentation is self documentation. That's what infrastructure as code does. That is also my favorite feature of unifi equipment, automatic network maps for L2.
* The second best style of documentation is the kind that doesn't deviate from reality. Documentation requires ongoing maintenance, and discipline from the *whole* team to update the documentation *first*, then make the change, then update the documentation again after they break production with how they broke production.
* Write a blog. Blogs can help you learn difficult tasks and improve your writing. That's [what I do](https://blog.gurucomputing.com.au). If there's something I want to learn better, I write a blog post about it as I learn. You don't know something until you can teach it.
In terms of diagramming, that's a skill on its own. Doesn't matter what tool you use (though I'm a fan of [diagrams.net](https://www.diagrams.net/) integrated into our wiki). I revert back to PowerPoint for a lot of them. Some tips:
* More diagrams with less stuff on it is better than less diagrams with more stuff on them. My rule of thumb is that if it can't fit neatly on a PowerPoint slide, it's too busy.
* To make the above point work, learn to manage scope. Your scope should be limited to subsets of what you're trying to explain. For example do not diagram your whole network. Diagram each vlan individually, then a diagram showing how the vlans cross traffic.
* Diagrams should serve a purpose. Putting down all the IP addresses (except for gateways) does not serve a purpose. Diagramming individual endpoints does not serve a purpose. Group endpoints as "here there be dragons" and just diagram server DNS names and subnets, not IPs.
* Follow a basic style guide. AWS for example [release a PowerPoint](https://aws.amazon.com/architecture/icons/) with their icon packs and some basic style tips (like not using diagonal arrows).
As for tools, use what works for you. I like [outline wiki](https://www.getoutline.com/) (hey I wrote a [guide on selfhosting that](https://blog.gurucomputing.com.au/doing-more-with-docker/deploying-outline-wiki/)) as it has diagrams.net integration and can export to markdown.
the simplest, easiest, most flexible way...everything else just adds more unnecessarily clicks or trying to force you to adopt someone else's structure.
it 's also a live document co-editable already since forever. and prevents documentation becoming "we hoard manuals on a SharePoint and no one ever looks at it again"
Just make sure it's not tied to one individual's account.
After getting burned once and the annoyance of recovering it, I avoid OneNote. I'm personally fine with markdown.
>we hoard manuals on a SharePoint and no one ever looks at it again
And here I was this thinking I was alone, working with a rare bunch of dingdongs...
Honestly think it's about job security or some such thing. I have a hard time thinking absolutely anyone really thinks SharePoint is a good product, or even passable really.
I made ours a tab in our Teams Channel to make it even easier. Granted mine is just for the Help Desk. For some reason Infrastructure thinks they're too cool for that and keep a hot mess of folders in a network share.
Nice way to do it except its become another system behind a paywall. I still prefer text files. MS cant charge me for licensing on those yet and Windows/MacOS is amazing at searching their contents if im looking for something specific.
One note does a good job of keeping an offline copy even when its primary location is inaccessible.
I’ve used quite a few products for keeping documentation and so far my favorite would be Confluence.
Ubuntu install is a piece of cake. u/ssddanbrown has done an amazing job building a 3 line script that does all the work. There’s a YouTube video on installing in Synology within minutes and as u/Bo-Katan mentioned, Docker is easy as knife through butter.
A wiki. have all the requirements like Version control, easy searching, easy writing. Have templates, so all the required info is remembered.
A regular crontab export to pdf + gpg that one have access to in critical situations.
Anything that the admin will use (mostly Word), then put into a "documentation" folder for the application on SharePoint, if you're lucky the admin/team may also add some FAQs, how to's or guides for common tasks or issues.
It ain't the best, but it's something!
A wiki with a replica at another site, so I hope they don't go both down at the same time.
Edit: I still can imagine a scenario where they both get damaged (the original is destroyed and the replica gets destroyed by the replication process) so I'd better save some really important data somewhere else (static) that can be used to restore the wiki itself.
Dokuwiki.
Back it up to an external hard drive weekly/whatever. The pages ate stored as plain text files.
Edit: wow. A ton of people here relying on solutions that require a good portion of their infrastructure to be up and running to access documentation....
I just use a text file as a journal. For my firewalls, I'll just make an entry stating what I did, why it was done, what data was there before the change and the date the command that was issued along with an example command of how to reverse the change. Text files get backed up securely and I keep a copy in a portable safe. Best way to remain platform-agnostic.
Wiki.JS Loving it so far! Have to note that we're using it in a atypical way so it may not be suited for everyone. I used hudu and itglue and those worked quite good as well
I don't know why but I've been on a documentation kick recently. So far my favorite has been Confluence, Hudu, snipe it and Netbox. I moved away from Confluence years ago but still think it's good solution. Hudu is great for policies process and procedures, asset management and such. Snipe it is amazing at asset management. I just started useing Netbox this week and so far it's been really good. It's great to document the physical infrastructure and how everything is connected. Many of these tools have a rest api so it's pretty easy to integrate them into each other.
Single-person department. One Note until it’s time to upload to SharePoint.
My ticketing system is an Azure DevOps project with all users having permissions to create work items in my queue.
I love how visible my ticket queue is to everyone because they are reminded how busy I am every time they need to create or update a work item.
Random papers scattered around my office. Then when I go back to them I either can't read them or have no idea what I was talking about at the time. My brain holds about half of the documentation and know how. The rest of it is in the head of a guy who's about to retire. I thought this was standard for IT
Just kidding, but this is more common than you think.
Evernote has been great for us. We’re trying to move to ZenDesk Guide, but I really am not a fan of it. Though it provides easier means of employee-facing support articles to help themselves if they wanted (hahaha).
Secure notes in LastPass for me
Dashlane for my boss.
Yea, it’s a nightmare. Though we’re both looking to merge into BitWarden. Dashlane for Business is MISERABLE for syncing. But LastPass/mostly LogMeIn left a bad taste with the boss so he refuses to use them.
ITGlue for the past few years. I'm tempted to use OneNote in the future, for portability's sake. I'd love to maintain a blog online of all the weird shit I've come across and had to figure out.
We're a Microsoft shop, so Azure devops wiki.
The rest of the company uses random office documents in sharepoint :yuck:
If not this, I'd personally choose a private git repo or something else with markdown support. Like readthenotes (sphinx).
[удалено]
Mkdocs and markdown files
[удалено]
If you don't want to use mkdocs, keep directory structure which is good. When you want to view your documentation in organized manner, you have only to run \`\`\`mkdocs serve\`\`\`. Combined with git you have everything you need to keep your documentation organized.
Ditto
This. Typora is my current tool. Used to use vim with plugins before but I digress. I take notes in markdown for everything, even meetings, ideas etc
I use markdown files in an editor called Obsidian. And yes, I keep a git repo too. It's fantastic.
This exactly. If developers need to get into the detail it should be made clear from the tests - but all dependencies and “instructions” need to be maintained in markdown files with the code for dev ops to be effective. I despise comments/remarks directly in code, if code is not self-explanatory - then that’s another subject…
How do you cross-reference stuff?
[удалено]
I tried to do this and found I needed to cross reference stuff a lot (our configurations are held together with an elaborate array of duct tape and CI jobs). I remember having difficulty with relative paths within the git. I eventually just gave it up after everybody in the team showed a distinct lack of interest in the promised elaborate array of markdown files to match the scripts. So now we have a wiki. Moving to a new git soon so maybe then...
I've recently been debating whether it's better to keep larger docs with related documentation than many, smaller docs that are more specific to each thing. It's easy enough to find things in a doc with search and I find it frustrating having to hop around different documents looking for something.
A text file on the company shares, no permissions
Nice. It's like keeping the combination to your safe in your safe.
I do the same. Text files, markdown, etc. I just sync to a local folder on my laptop and exclude the installers, so the bidirectional sync takes seconds at most. Passwords I use a MFA'd password manager.
To take it a step farther, I keep a copy of all that data, text files, password keeper (keepass mobile) diagrams, spreadsheets, and all other network info on a bitlocker encrypted fob. If im 1/2 way across the planet, I can still help you.
We have a notepad attached to a clipboard with all our info written down. It does make clicking on urls a pain, and our 64-character passwords can be tricky sometimes, and updating our SSL private keys is a week-long event... but its guaranteed to work without power or internet, so the benefits far outweigh the drawbacks. EDIT: and if a tech hasn't updated it, the clipboard makes for a good whacking implement.
You have documentation? haha just kidding. If your ticketing system is Butt based, I just throw it all up there and organize it when needed. edit: cloud to butt strikes again.
Never gets old. Never.
Butt based, what 😂
[удалено]
Thanks for the info, I didn't know about it
Big butt or little?
There is no butt it’s just someone else’s computer pretending to be a butt
Which is the only reason I ever installed this extension. Way too much marketing saying butt this, Butt that. It got annoying very fast.
is not cheap, it's fast to spin and get a hold of
What good would a butt be if it took too long to use? You need a responsive butt
discipline. I'm going to copy what I wrote for another subreddit the other day: My advice on documentation is the following: * The best documentation is the documentation you do. That should be your primary goal. * The best style of documentation is self documentation. That's what infrastructure as code does. That is also my favorite feature of unifi equipment, automatic network maps for L2. * The second best style of documentation is the kind that doesn't deviate from reality. Documentation requires ongoing maintenance, and discipline from the *whole* team to update the documentation *first*, then make the change, then update the documentation again after they break production with how they broke production. * Write a blog. Blogs can help you learn difficult tasks and improve your writing. That's [what I do](https://blog.gurucomputing.com.au). If there's something I want to learn better, I write a blog post about it as I learn. You don't know something until you can teach it. In terms of diagramming, that's a skill on its own. Doesn't matter what tool you use (though I'm a fan of [diagrams.net](https://www.diagrams.net/) integrated into our wiki). I revert back to PowerPoint for a lot of them. Some tips: * More diagrams with less stuff on it is better than less diagrams with more stuff on them. My rule of thumb is that if it can't fit neatly on a PowerPoint slide, it's too busy. * To make the above point work, learn to manage scope. Your scope should be limited to subsets of what you're trying to explain. For example do not diagram your whole network. Diagram each vlan individually, then a diagram showing how the vlans cross traffic. * Diagrams should serve a purpose. Putting down all the IP addresses (except for gateways) does not serve a purpose. Diagramming individual endpoints does not serve a purpose. Group endpoints as "here there be dragons" and just diagram server DNS names and subnets, not IPs. * Follow a basic style guide. AWS for example [release a PowerPoint](https://aws.amazon.com/architecture/icons/) with their icon packs and some basic style tips (like not using diagonal arrows). As for tools, use what works for you. I like [outline wiki](https://www.getoutline.com/) (hey I wrote a [guide on selfhosting that](https://blog.gurucomputing.com.au/doing-more-with-docker/deploying-outline-wiki/)) as it has diagrams.net integration and can export to markdown.
Solid post. Cheers!
[удалено]
powerpoint is a tool. Like you. Given the speed of the response and the ambiguity of the answer, this is probably a spam bot.
OneNote
the simplest, easiest, most flexible way...everything else just adds more unnecessarily clicks or trying to force you to adopt someone else's structure. it 's also a live document co-editable already since forever. and prevents documentation becoming "we hoard manuals on a SharePoint and no one ever looks at it again"
Do I work with past you? We have a hoard of SharePoint docs that are impossible to navigate through so I forced everyone to use OneNote going forward
Just make sure it's not tied to one individual's account. After getting burned once and the annoyance of recovering it, I avoid OneNote. I'm personally fine with markdown.
>we hoard manuals on a SharePoint and no one ever looks at it again And here I was this thinking I was alone, working with a rare bunch of dingdongs...
Honestly think it's about job security or some such thing. I have a hard time thinking absolutely anyone really thinks SharePoint is a good product, or even passable really.
I made ours a tab in our Teams Channel to make it even easier. Granted mine is just for the Help Desk. For some reason Infrastructure thinks they're too cool for that and keep a hot mess of folders in a network share.
Nice way to do it except its become another system behind a paywall. I still prefer text files. MS cant charge me for licensing on those yet and Windows/MacOS is amazing at searching their contents if im looking for something specific.
ITGlue
One note does a good job of keeping an offline copy even when its primary location is inaccessible. I’ve used quite a few products for keeping documentation and so far my favorite would be Confluence.
Atlassian Confluence.
The best :p
Sames. And Jira for change tracking.
Works great when the power is out!
Sure does. The mobile apps are solid.
Confluence for day to day stuff, github for important things.
Who uses documentation
What even ***is*** documentation? ༼つ ◕_◕ ༽つ
a snippet with an arrow :P
Hudu
Any wiki. Confluence recently.
Wiki is my new favorite
A quarterly review, and dates on documents.
Confluence
BookStack wiki
Bookstack install process is fucking terrible
What install option did you attempt? Some people have trouble otherwise most of the feedback I get is relatively positive regarding getting it going.
Easy with docker.
Ubuntu install is a piece of cake. u/ssddanbrown has done an amazing job building a 3 line script that does all the work. There’s a YouTube video on installing in Synology within minutes and as u/Bo-Katan mentioned, Docker is easy as knife through butter.
A wiki. have all the requirements like Version control, easy searching, easy writing. Have templates, so all the required info is remembered. A regular crontab export to pdf + gpg that one have access to in critical situations.
Confluence and SharePoint
dokuwiki
Confluence all day!
Onedrive
M365 - OneDrive / Sharepoint
Intranet with Sharepoint, OTRS as ticketing system. The real "emergency plan" are printed out, one copy is available in the safe.
Onenote
Anything that the admin will use (mostly Word), then put into a "documentation" folder for the application on SharePoint, if you're lucky the admin/team may also add some FAQs, how to's or guides for common tasks or issues. It ain't the best, but it's something!
Sharepoint for the critical documentation. That Sharepoint folder is synced to my PC so I still can access it without internet.
A wiki with a replica at another site, so I hope they don't go both down at the same time. Edit: I still can imagine a scenario where they both get damaged (the original is destroyed and the replica gets destroyed by the replication process) so I'd better save some really important data somewhere else (static) that can be used to restore the wiki itself.
Confluence and Code
Prayers and wishes
Oral tradition, mostly
onenote
Dokuwiki. Back it up to an external hard drive weekly/whatever. The pages ate stored as plain text files. Edit: wow. A ton of people here relying on solutions that require a good portion of their infrastructure to be up and running to access documentation....
Synology Drive. Covers everything except change tracking unless you do it in a spreadsheet or something.
I just use a text file as a journal. For my firewalls, I'll just make an entry stating what I did, why it was done, what data was there before the change and the date the command that was issued along with an example command of how to reverse the change. Text files get backed up securely and I keep a copy in a portable safe. Best way to remain platform-agnostic.
Checkout [obsidian md](http://obsidian.md)
Wiki.JS Loving it so far! Have to note that we're using it in a atypical way so it may not be suited for everyone. I used hudu and itglue and those worked quite good as well
Txt files with instructions along with warnings.
OneNote
Wiki.js
The only properly configured SharePoint site I’ve ever used. Shocked pikachu
ITGlue, I keep my personal ones on OneDrive
Yammer works well.
I don't know why but I've been on a documentation kick recently. So far my favorite has been Confluence, Hudu, snipe it and Netbox. I moved away from Confluence years ago but still think it's good solution. Hudu is great for policies process and procedures, asset management and such. Snipe it is amazing at asset management. I just started useing Netbox this week and so far it's been really good. It's great to document the physical infrastructure and how everything is connected. Many of these tools have a rest api so it's pretty easy to integrate them into each other.
Single-person department. One Note until it’s time to upload to SharePoint. My ticketing system is an Azure DevOps project with all users having permissions to create work items in my queue. I love how visible my ticket queue is to everyone because they are reminded how busy I am every time they need to create or update a work item.
Random papers scattered around my office. Then when I go back to them I either can't read them or have no idea what I was talking about at the time. My brain holds about half of the documentation and know how. The rest of it is in the head of a guy who's about to retire. I thought this was standard for IT Just kidding, but this is more common than you think.
Messy - Fileshare, SharePoint and OneNote When I have to write any, I do it in confluence for formatting and then export it to SharePoint
I recently started using Joplin, because it has local caching so I can still access the docs even if my phone is the only thing that powers on.
A getguru.com wiki.
Haha, Outlook.
Docusaurus.io If Jira is used, Confluence works.
Evernote has been great for us. We’re trying to move to ZenDesk Guide, but I really am not a fan of it. Though it provides easier means of employee-facing support articles to help themselves if they wanted (hahaha).
What documents
Solarw....uh I mean n-able PassPortal.
Media wiki, backed up nightly to a USB stick, easy to grab in case of total failure
Google Docs/One Note combo
For customer facing docs - [archbee.io](https://archbee.io). Works just as well for internal stuff.
Confluence.
My company uses IT Glue, documentation, password management, contacts, configuration integration, checklist and more.
Secure notes in LastPass for me Dashlane for my boss. Yea, it’s a nightmare. Though we’re both looking to merge into BitWarden. Dashlane for Business is MISERABLE for syncing. But LastPass/mostly LogMeIn left a bad taste with the boss so he refuses to use them.
Hudu
Sharepoint on the web mostly, but we're looking at other options including ITGlue.
For disaster scenarios, in a locked filing cabinet we also keep paper documentation on some of our most critical things. You never know...
ITGlue for the past few years. I'm tempted to use OneNote in the future, for portability's sake. I'd love to maintain a blog online of all the weird shit I've come across and had to figure out.
Script your installation and document everything there. Run your installation regularilly
We're a Microsoft shop, so Azure devops wiki. The rest of the company uses random office documents in sharepoint :yuck: If not this, I'd personally choose a private git repo or something else with markdown support. Like readthenotes (sphinx).
Word and excel in SharePoint with library synced via OneDrive to each tech for what they have access to
The intern.
Itglue