Hot answers tagged documentation
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 ...
43
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 ...
13
I know that this isn't free, but I think the Altassian products could suit your needs. Specifically the Confluence Wiki could help with your documentation and the JIRA module could do issue/bug tracking.
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
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 ...
11
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 ...
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 ...
10
You should work with your boss/HR people to have a series of written policies, adopted by the supervisors, that outline how various issues are handled and what is expected of employees. These can vary depending on the business, but basically you would have documents that specify what is and isn't allowed on your network and computer systems and what 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
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 ...
8
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. ...
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
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 ...
8
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 ...
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 ...
8
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)
...
6
You say you're building the sytems from scratch, so it sounds like you're more interested in the automated setup than you are grabbing configuration from a "live" system.
The installation of every version of Windows since Windows 2000 has been fairly straightforward to automate via "answer files".
Unattended Installation Fundamentals (Windows 2003)
...
6
Doku Wiki or Sharepoint for other things that fit into a chart.
You get used pretty fast to posting on a wiki and the syntax is not so complex really. It is very easy to organize information and make it easy to find it later on by someone else.
I use visio to make graphs for clearer explanations (export as JPEG).
6
We're using a wiki. In fact, we're using MediaWiki. On top of MediaWiki, we have the Semantic Mediawiki extension installed, which actually turns our MediaWiki into something of a loosely typed database that we can query with Category, title, contents, etc.
For instance, let's say I want to see all the network cnames that route through Cluster F. All I need ...
5
Acrobat Connect Pro and Captivate look awesome.
Many people swear by Camtasia. I used it in the past, and indeed, it's a great product. Here's an open source alternative: CamStudio.
And here's a round-up of several screencasting tools.
5
In my previous work I used Twiki. It worked fairly well.
Next to that, I tend to automate most tasks, and document the scripts (not always with much enthousiasm, but still... ). Documenting scripts is easily done in the process of designing them, so no real overhead...
The combination of both (and using version control for the scripts) did the trick ...
5
Institutionalizing Knowledge
We started off with documents. Then we stored some of them in Sharepoint libraries. Then recently we moved to the Sharepoint wiki. I like the wiki's low-friction approach in quickly updating things, though Sharepoint's wikis leave some things to be desired in graphics support and formatting support for things like tables. It's ...
5
You haven't specified directory
find . -type d ! -perm -777
Manual page that you cited states that pathname should come before expression. So in this case a dot "." comes before "-type d ...". The latter are not options per se. In fact -type and -perm are parts of boolean expression that find tries to evaluate for each file.
5
It depends on the target audience for your documentation.
For helpdesk (level 1) types, a checklist is the correct way to go; of course, this presumes that there are higher levels of support with the deeper knowledge you describe.
If the documentation is for the systems group, I always err on the side of more documentation. It's hard enough to have ...
5
The standards you are looking for are the
TIA/EIA-568 Structured Cabling Standards
These standards determine everything from precise dimensions of peripherals to their physical properties to labeling criteria. It has various sub sections that deal with particular areas in a structural cabling topology like Horizontal cabling, vertical cabling etc.
5
Two things...
The most important document for you to read is the Oracle Solaris ZFS Administration Guide. It provides a comprehensive description of ZFS features and terminology. It also gives excellent examples.
Beyond that, you may want to look at NexentaStor as an option if you're primarily interested in the storage aspects of ZFS. It's a ...
5
To an extent, what you include will depend a good deal on who you are documenting for. Are you documenting for administrators? For users? For programmers? All of the above? Just like when you are designing a site, you need to look at the use cases and solve them.
Things I would consider critical for documentation provided to me as a programmer and/or ...
5
For web based "Choose Your Own Adventure" style documentation it is hard to beat a wiki.
It is easy to have a page that looks like:
DHCP issues
Run ipconfig [help running ipconfig] and note the assigned IP address.
If the IP address starts with:
169.254 see [diagnosing dhcp failures]
192.168 see [tracking down and reporting a rogue dhcp ...
5
I use http://www.dokuwiki.org/ because it is easy to set up, has a lot of features (my favourite is "Downloadable Code Blocks"), allows the use of ACLs and uses .txt files which don't depend on any Office/Office Version and are easy to back up.
It has everything you asked for except "if you don't have access to a doc, you don't see the link to that ...
Only top voted, non community-wiki answers of a minimum length are eligible
