General discussion

Locked

IT and Support Documentation

By secure_lockdown ·
I think a great traits one can possess is the ability to acknowledge and see his or her weak areas. I have come to realize that my documentation --> "sucks"! And I also think my predecessors didn't do a very good job about proper documentation and setting down a set of standards and procedures.

I find as I am tackling more complex jobs - my support documentation is getting more complex as well. The simple text files and HTML files don't cut it anymore. Keeping track and updating revisions is a nightmare - that one tries to do everything else but the required documentation.

I am looking at possibly DocBook and/or CVS. I have never used them. so before i invest time learning one or both of them - i thought i might throw the question out to the learned audience here and see what other people in similar situations do.

what do you use for creating documentation?

what do you use to keep track and manage versions and changes?

what do you use to distribute documentation to other IT staff and have them make changes & updates?

lastly, any good tips or advice you have gained from the field that you use and think they save you time and aggravation?

you might also want to include a little blurb of what kind of documentation you write. a software developer will have a very different method of documentation that a system admin or support analyst.

regards,
SL

This conversation is currently closed to new comments.

8 total posts (Page 1 of 1)  
| Thread display: Collapse - | Expand +

All Comments

Collapse -

Sharepoint

by JamesRL In reply to IT and Support Documentat ...

Just started to implement Sharepoint as a way to track documentation. It is being used by a wide range of people - developers, support analysts, testers etc.

Its free(CALs notwithstanding). It integrates into Outlook and Office. Its fairly easy to set up.

James

Collapse -

Thats an interesting idea...

by secure_lockdown In reply to Sharepoint

But the prerequisite is MS Office, MS Messenger and IE if you want to take advantage of it's bells and whistles. Probably won't fly with our uber hardcore *BSD contingent. But an interesting approach none the less.

Thanks

Collapse -

Haven't tested but

by JamesRL In reply to Thats an interesting idea ...

I don't use MS Outlook and of course I still get notifications from the Sharepoint server. And I don't use hte functionality in Office that integrates to sharepoint because I am using an older office version.

Nonetheless it seems a usefull tool.

James

Collapse -

I use

by Jaqui In reply to IT and Support Documentat ...

both docbook and xml/xhtml

docbook for fairly simple documentation sets, but I use xml xhtml for more comprehensive compilations.

with the xml/xhtml setup, you easily break down the documentation into small easily maintained files.
it's not truly meant for revision control, but by saving original with a date created in the filename, then saving back into the original name, you have the versions needed to back track when needed.

if you send me your email I could also send you a base php/mysql setup that is designed exactly for this purpose. ( open source from a manual's companion cdrom )
the php/mysql website script is designed to allow you to have multiple users editing documents, keeps track of changes, dates, and users can only work on documents they are granted permissions to.
it's more complex than I need, but it may be what you want.

Collapse -

Sharepoint & Visio

by dafe2 In reply to IT and Support Documentat ...

I see James already mentioned Sharepoint (GREAT tool)............any & all my drawings are done with Visio 2003 using CISCO, HP and any other Stencils necessary.

Collapse -

DocBook and XML

by chris In reply to IT and Support Documentat ...

Hi SL,

We've (http://www.neodoc.biz) been using DocBook XML for the past 5 years. It has allowed us to manage thousands of documentation pages divided into several manuals, and translated to 7 languages (English, French, Spanish, German, Italian, Russian and Chinese).

Here's an overview of how we work: our documentation projects are driven by the Borges Documentation Management System (http://sourceforge.net/projects/borges-dms) and run on Mandrakelinux. We create a master file (master.top.xml) in which we write our Table of Contents. Then Borges (through a "make" command) generates each module for a said master file in each of the defined languages. The writer uses the DocBook XML grammar to segment his text.

Through Borges' workflow, each module passes several steps:

- write
- tproof (technical proofreading)
- pproof (pedagocical proofreading)
- ispell
- lproof (linguistic proofreading)

When a module reaches pproof, Borges assigns IDs to every element (para for paragraph, for instance). Those IDs are very important since they enable us to know when an original file (usually in English) has changed and that the translation file needs to be synched. We also use revision attributes to help translators spot where a change has occurred. For example, <para ID=my_id revision="1"> will indicate that this paragraph has changed semantically speaking.

In order to keep track of the different versions of the modules, we use CVS. All versions of files are stocked on a CVS server, hence nothing is lost (you can revert easily to a previous version for instance).

When we interoperate with marketing and R&D, we use two ways:

- for R&amp they receive an e-mail stating where to fetch the XML file. They edit it with an editor like emacs, vi, or whatever text editor;

- for marketing, we usually send them a PDF file of the module (or of the whole manual) for their review. We can also generate an HTML version of both modules and manuals.

Finally to answer your last question, we write software-related documentation, printing documentation, marketing, etc. Borges, DocBook and a text editor can do the trick for you!

Of course, you need the stylesheets which you can then customize (see the Oasis web site). Mind you, you can use the stock ones, but they are fairly "harsh". But a minimal customization should do the trick.

Hope this helps.

Christian Roy
Cofounder
http://www.neodoc.biz

Collapse -

you sir..

by secure_lockdown In reply to DocBook and XML

...have one helluv a company and one great idea. thanks a lot for the post.

Collapse -

myCMDB.com Network Inventory Documentation

by techrepublic In reply to IT and Support Documentat ...

We operate an ASP application, which addresses documenting the network environment.
It covers installed hardware, software, machine purpose, classification, backup schedule ?
The service includes an online system scanner which performs a baseline scan (OS, Software, KBs, System Info). On top of that you can add non discoverable attributes (location, purpose, classification ...).

Our customer base consists of independent consultants who support different clients as well as small/mid size companies who track between 50-5000 configuration items. It reduces the knowledge loss when IT staff changes (like any documentation does) but it still requires admins to perform manual steps and to update configuration changes (e.g. changed backup schedule).

This should not be considered a sales post (although it may sound like one) but as one possible solution on how to document your network and reduce knowledge loss/risk.

Jim Davis
myCMDB.com
<How do you document your network?>

Network Inventory and Configuration Management

Back to IT Employment Forum
8 total posts (Page 1 of 1)  

Related Discussions

Related Forums