What Do You Place In Your Documentation?

[ChrisBrown]

This is a general, but broad question.

What do you put in your documentation in regards to: code, servers, site structure, accounts, etc.

I'm in charge of all web related items at my organization, and I have been spear heading documentation of everything from code to servers, etc. But I want to know what you all do in your practice; what you feel is important and how you approach it. What do you wish that someone would have documented in the past? What helps you everyday?

Thanks for the assistance, I really appreciate it.

[Robert Wellock]

Server platform; OS, Graphics Editing Packages available, user-agents used, server-side functionality and liveware, it depends upon what purpose you are wanting to document for.

[Compguy Pete]

I would add to what Robert has by saying...

You should include how to use any online control panels you may use. How to setup email accounts.

If you do a lot of hosting I would also say a listing of prices to install scripts and other items you can charge for.

In my welcome kit it has netadmin instuctions, FTP info, email, troubleshooting tips and billing info.

[ChrisBrown]

How detailed do you go in your style guides?

[couchmonkey]

Methinks we need to know more specifics. I read your question as being about internal documentation for fellow employees to use, but it looks like some others read it to be documentation for clients using your sites.

If you're working on external documentation, I'd need to know more about what your clients do with your sites.

I just started a new job recently so if you are making internal documentation, here's a bed-time story for you. ;)

I've found the hardest part of adjusting to my new job was wading through vast, complicated file systems. We have three servers containing multiple sites (not to mention a pile of other junk) plus a content management system. Files were stored a little differently on every system and I spent a lot more time looking for things than working on them in my first week or two.

Files within files contributed to that problem too. If you have a lot of web pages that "include" other web pages, it might be nice to create some screenshots showing the "anatomy" of those pages...what files do they contain? Figuring this out on my own was kind of hard and very tedious.

Finally, lists of typical testing procedures and environments would have been nice. A big part of my job is fixing bugs, and I made quite a few mistakes early on because I couldn't test the pages I was changing - they occured in the middle of complex signup processes that require a special login to use. Eventually someone pointed out a page we have set up where I can start a new signup any time I want and go through the signup flow. This made things so much easier, but I would never have known it was there if he hadn't happened to be around while I was working on a bug one day.

HEY! Wake up!!

Okay, that's my story. My apologies if it was useless to you, but I feel better! ;) Maybe if you give some more specifics I can give a more useful answer. Good luck!

[ChrisBrown]

To answer your question, this is all internal documentation for all types of users. Those who manage the server, those who code, those who create graphics, and those who place the content.

[couchmonkey]

One thing I found very useful in the documentation that was left for me was a list of our sites including their URLs on our production, development and preproduction servers as well as the FTP information for the servers I have access to. I used this table as often as all of the other documentation I was given combined.

Of course if you aren't running many different sites in your company, it may not be so useful, but I would still recommend something like it.

It might be a good idea to have some sort of standards for coding as well, I found a document on that in my company and found it pretty useful, but it depends on how picky you are about everyone writing stuff the same way.

[ChrisBrown]

When you refer to standards of coding, are you refering to how code is laid out and what sort of documentation is included in the code itself?