Hot answers tagged

52

It depends on the size of the network, number of users, number of nodes (computers, servers, printers, etc.) and the size of your IT staff, among other things. It also depends on your goal. Are you documenting the network for training and maintenance purposes, insurance/loss prevention, etc? Personally, I document my networks in such a way that I know I ...


50

Document the heck out of everything. There was a thread on Slashdot recently about starting documentation, which inspired me to write down my thoughts about documentation. My key points were: Principle #1: It Is Never Done Documentation is an on-going effort that will always lag behind what is in production. Changes are made ad-hoc, things moved around ...


17

I'm surprised that there are so many jaded answers here. Here's my $0.02. First, relax. You're in your first more senior gig and have all sorts of new challenges. Second, buy and read Limoncelli's The Practice of System and Network Administration When you start, remember that you're an outsider looking in. That's cool because you're coming with no baggage ...


15

since 2003 I'm documenting everything in our inhouse wiki. server hardware specs guarantie information network information and of course installed software and configuration workflows e.g. howto add or delete a user and give him/her access to all relevant services important links link to all your web-interfaces link to the monitoring URLs (nagios,...


14

Actually neither, we use Documentation As-a-Testcase That being said we have written documentation that goes with Documentation As-a-Manual. We had checklists in place but when growing we found them to be error prone and really failing on the system as a whole. We do however have kind of "Documentation As-a-Checklist" installed, that is - as mentioned ...


13

Here are a few web pages that will help get you started: Creating and Formatting Man Pages Creating Your Own MAN Page Create Your own Man Page How to Write a Man Page What you need to know to write man pages A couple of useful tools: txt2man help2man


13

Start by not changing anything. STart documenting at least for yourself and think about changes. Give it a month, then slowly propose changes. But do not jump in head start. How high up the food chain will you be? The end users for the company use a mixture of 4-5 different distros of Linux in addition to both Windows and Mac. This is a like to ...


13

The company's IT operations seem a bit unorganized so I know I will need to work to setup processes.. I suspect the first thing you may need to do is try to avoid making assumptions about what you may believe they need and instead try and figure out why things got to the point it is. For example if they hired you as a senior system administrator, are ...


12

First, be careful not to document Active Directory itself. Microsoft has already done that. It is not your responsibility, and it will reduce the time you have to document the configurations, policies, and procedures specific to your installation. Here is a list of things that you should document. Explain your computer, user, domain, and OU naming ...


12

While you realize that while everyone wants (and needs) documentation, you also need to recognize that no-one has time to read and study the stuff. So, don't write documentation that needs to be studied - instead, structure your documentation in a way that allows someone to quickly find the information they need, when they need it - which may well be while ...


12

Unless there's going to be a lot of content switching tiers, I'd recommend separate wikis, as MW was never built for solid access control. Read http://www.mediawiki.org/wiki/Security_issues_with_authorization_extensions first and decide whether it's worth the effort. There's a lot of warnings and exploits that can circumvent the protection methods. If you ...


11

When writing mine I've always devolved into writing two three sets. The get-er-done checklist, with a MUCH LONGER appendix about the architecture of the system including why things are done the way they are, probable sticking points when coming online, and abstract design assumptions. followed by a list of probable problems and their resolutions, followed by ...


11

The first thing to realize is that not all find commands are created equal. The find you will find on a Linux system is different then what you will have on a BSD-based system like OSX. The reference you are going off is for Linux. For the find command the '-type' option is an expression and must be after the path. If you read further down the man page ...


11

I don't agree that you should try to get rid of Mac/Linux. Unless those OS choices are negatively affecting those users productivity, it would make more sense to allow them to use the OS that grants the most productivity which in turn leads to higher profits, which makes your boss and the company happy. I do agree that you should go in, document, diagram, ...


11

Writing is a discipline. I've done a lot of it, and I have as much of the basics down as an untrained person can get without documentation being a top part of my job. Time has shown me what documentation I produce will actually get read, and what will go on the Shelf of Eternal TL;DR. This is in fact the number one rule of writing anything: Know your ...


10

I find it's best to incorporate all of the following: Prose: A general overview in paragraph form, which helps with initial big picture and also can describe evolution over time Tables: Tabular lists, either address-keyed, environment-keyed, or machine-keyed (preferably all of the above) Diagrams: Definitely need diagrams with multiple levels of detail. ...


10

Check out RackTables: http://racktables.org/


9

All of these things should be documented in detail, although when the operation is standard for the operating system, application server, web server etc you may be able to assume the IT operations people know how to do that. Installation: document everything about how it is installed and configured, including how to tell if it is operating correctly. Tell ...


9

I assume this is a long term documentation effort, not just trying to capture a snapshot of the current configuration. The wiki works now and might keep you sane for a while but if your environment changes quickly you will have a serious problem. You will always have to make sure the cron jobs are properly written, run in a timely fashion, get written for ...


9

The first thing you do is... nothing except get to know the people and get to understand the business. Find out what the needs and expectations are. All those different Linux distros sounds like a pain to me, and one I'd like to try and reduce down to one distro if I could... but what if there are 5 distros in use for a perfectly good reason? Same for the ...


9

What to document? "EVERYTHING!". As a sysadmin you must assume that one day you will be run over in the parking lot by a user who is upset you wouldn't let them download porn on the work network. Your successor should be able to pick up your documentation, read it, and take your place with virtually no questions/problems (at least in the ideal fantasy ...


9

A customer just asked me for this, so I compiled a short list of links I have found useful over the years. Not necessarily in the best order, and by no means complete, but thought it might make a good addition for anyone hitting this question: http://www.nex7.com/readme1st (work in progress, can PM me if you have questions) http://9to5mac.files.wordpress....


8

Commenting on the tooling. We've tried online wiki's but found a number of limitations, which may be personal taste, but include document structure and most critically having to be connected to the documentation server. Being connected is a serious problem if you are either offline or onsite (obviously you can mitigate the onsite with a secured SSL ...


8

Of course you should care. After all, any job worth doing is a job worth doing well. 1.) It's already been said but it needs repeating for reiteration. Document, document, document. Use excel spreadsheets, notepaper, quill and parchment if you have to. Several thousand mead notebooks like in the movie "Se7en" if need be. Either way, lay it out clear, ...


8

Disaster Recovery Plan is the proceedures the administrators do to restore normal business workflow. Business Continuity Plan is what end users do to remain productive when normal business workflow is interrupted.


8

You mean like RFC 5737? The blocks are: 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3)


8

The main user-visible differences since 0.23.x are: more language features like better conditionals - the Language Tutorial that you found is definitely the best way to find out what's available in manifests now. all your manifests and plugins (custom facts, custom types and providers) should now be in a module directory structure and you should be using '...


8

I don't know that there are industry standards, but there are plenty of options. Some have been discussed here: What is the most effective solution you used to label cables? What’s the best way to label cables in a data center I think the "standard" is Pick a labeling methodology for your site. Document it. Follow it. Kill anyone who deviates from it in ...


7

We have started to use DokuWiki where I work. From Dokuwiki's website: DokuWiki is a standards compliant, simple to use Wiki, mainly aimed at creating documentation of any kind. It is targeted at developer teams, workgroups and small companies. It has a simple but powerful syntax which makes sure the datafiles remain readable outside the ...


7

We're using MediaWiki [1] in our company, works really well for internal documentation. Powers wikipedia as well. http://www.mediawiki.org/wiki/MediaWiki



Only top voted, non community-wiki answers of a minimum length are eligible