This forum is in permanent archive mode. Our new active community can be found here.

How Do I Properly Write Documentation?

edited September 2010 in Technology
I've recently come up with a method of combining multiple Symantec Ghost Boot systems into one multi-boot USB key. I've been asked by my co-workers/bosses to write up documentation on the process so that they can duplicate it if necessary (read: if they decide to fire me in the future). I've never written documentation before, so I was wondering if you guys would have any tips or examples I could look at for reference.

Remember some documentation I've read in the past and, based on what I can remember, here's what I've got so far:
Subject: How to Create a Multiboot USB drive for Norton Ghost on Windows 7
Author: Victor Cyrus Khaze
Date: 09/29/2010

Introduction:
This guide aims to provide a comprehesive, step-by-step, guide to creating a USB drive capable of booting multiple different driver versions of the Symantec Ghost Network Client.

Software Needed:
HP USB Disk Storage Format Tool (http://files.extremeoverclocking.com/file.php?f=197)
Windows 98 MS-DOS Boot Files (http://files.extremeoverclocking.com/file.php?f=196)
Syslinux (http://syslinux.zytor.com)
Symantec Ghost Boot Wizard (part of Symantec Ghost Solution Suite)

Comments

  • You basically just write instructions. Pretend you are writing a FAQ to a video game. Just like that. If you need more help, go look at documentation on open source projects that have good documentation. Here are some examples.

    http://docs.python.org/
    http://www.postgresql.org/docs/9.0/static/index.html
  • I have to do a lot of documentation for my job, ostensibly for the same reason. What you've got so far looks good. The next thing to do would be break it down step by step and include screen shots every step of the way, if possible. While you may understand everything you're doing, you almost have to write it from the standpoint of "if one of the receptionists had to do this, could they follow my document and get it to work?" I don't have a copy of anything I've done on me right now but I could shoot some demo docs over to you tomorrow morning if you'd like. You want it sent to your email in your profile or a different address?
  • I'll try to dig up some technical documentation I've written that isn't protected, proprietary, or otherwise non-public. Technical writing and documentation are a big part of what I do.
  • I have to do a lot of documentation for my job, ostensibly for the same reason. What you've got so far looks good. The next thing to do would be break it down step by step and include screen shots every step of the way, if possible. While you may understand everything you're doing, you almost have to write it from the standpoint of "if one of the receptionists had to do thiCVvw my document and get it to work?" I don't have a copy of anything I've done on me right now but I could shoot some demo docs over to you tomorrow morning if you'd like. You want it sent to your email in your profile or a different address?
    Yeah, that's fine. Thanks!
    I'll try to dig up some technical documentation I've written that isn't protected, proprietary, or otherwise non-public. Technical writing and documentation are a big part of what I do.
    Thanks a lot!
  • RymRym
    edited September 2010
    This is a short, simple document I wrote for non-expert troubleshooters. If anything were seriously wrong, I expect them to come to me, and this is designed to lead them into gathering much of the necessary information ahead of doing so. It's part of a much larger troubleshooting document. The formatting here is somewhat off, as I grabbed it from a wiki.

    Troubleshooting NTP Problems

    1. Overview

    Correct time is important for production trading and reporting servers. Furthermore, verifiably correct time is important for compliance purposes. The following are basic troubleshooting procedures and tools.

     

    2. Specific Problem Resolution Procedures

    There are four kinds of alerts associated with NTP. One, sys:ntpd, is associated with Linux servers. The rest are generated by the members of our NTP synchronization cloud.

     

    A. sys:ntpd Alarms

    This alert indicates that the server in question is not properly synchronizing with the NTP cloud. It returns a "1" if ntpd is running but not synchronized, and a "2" if ntpd has hung, crashed, or entered a weird state. (These are the same values that the "ntpstat" will return as exit codes). If several servers experience this error simultaneously, or the ntp cloud itself is experiencing errors, troubleshoot the cloud before checking on individual servers.

    Log into the server and run:

       ntpstat 
    This should give you a good indication of what is going on. You can verify the alert by checking the command's exit code.

     

    If ntpd is not running or hung (error code 2), restart it (as superuser):

       service ntpd restart 
    or
       /etc/init.d/ntpd restart 
    If any errors occur other than firewall errors, investigate them.

     

    If ntpd is indeed running, but is simply not synchronized, run:

       /usr/sbin/ntpq -c peer
    It should return the following list of peers. (The data returned on said peers will vary. A "+" noted next to a peer indicated that it is a candidate for synchronization. A "*" indicates that the server has synchronized with it.)
            remote           refid      st t when poll reach   delay   offset  jitter
       ==============================================================================
       +ny2ts1.ny2.xxxx time-b.timefreq  2 u  289 1024  377    1.505    4.232   4.285
       *va1ts1.va1.xxxx time-c.timefreq  2 u  304 1024  377    8.362    5.872   0.073
       +nycorp1ts1      time-a.timefreq  2 u  259 1024  377    1.994   -9.217   0.259 
    It these three peers are not the ones listed, check /etc/ntp.conf to make sure that it is the current standard one.

     

    If the peer list looks ok, verify that the ntp drift file (/etc/ntp/drift) exists and is writable to user "ntp". If it does not, DO NOT COPY one from another server. Simply be aware that ntpd may take a long time to synchronize before it has generated one. You may be able to find a valid one at /var/lib/ntp/drift. Do not borrow a drift file from any other location or source.

    Restart ntpd as above. If it fails, check the current time on the server:

       date 
    If it is more than a minute or two off from a known good time source, stop ntpd, run the following, and then restart ntpd to forcibly re-synchronize the time. (Note that this should not be done on production trading servers during trading hours except in an emergency and with the knowledge of the backoffice).
       ntpdate ntp1.xxxx.net 
    Any member of the ntp cloud can be used.

     

    If ntpd still fails to start or synchronize, contact Brandon DeCoster.

     

    B. sys:ntp_peer and sys:ntp_stratum Alarms

    These alerts indicate that a time server in the ntp cloud has lost its synchronization with NIST, stopped running its ntp service, or otherwise failed. While this is a serious error, the cloud as a whole will continue to provide accurate time so long as at least one of its members maintains synchronization with NIST. To get more information about the error, run the following:
       ntpq server.xxxx.net -c peer 
    This will show you the potential NIST sources. If the time service or device has failed, it will return nothing.

     

    C. sys:ntp_rootdispersion Alarms

    These are minor errors. They are triggered whenever a member of the NTP cloud is momentarily experiences a high root dispersion or is in the process of switching between NIST sources. This can be ignored unless it persists over the course of hours on a single cloud member or if all three cloud members experience it simultaneously. If the alarm persists, investigate the time sources the server is using (with the tools below) and ensure that most or all NIST sources are responding. Fewer active NIST sources will increase the likelihood of this issue occurring.

    Note that root dispersion indicates possible error, not actual error: multiple local NTP servers would need to experience this problem for a long period of time (more than a few minutes) simultaneously in order for there to be any serious danger of our time being skewed.

    D. Back Office Report Issues

    The [[NtpBackOfficeReportingScript][NTP Back Office Reporting script]] creates a snapshot of the state of the NTP cloud three times per day. It rarely shows a problem, and reports nothing that is not already monitored in Spectrum more effectively. Occasionally, however, it will indicate that a trading server is synchronized with a local NTP server that has a large possible (not actual) error. In that case, verify through the NTP logs that the server in question resynchronized to an alternate server within a reasonable time (within 1024 seconds) after the report was generated. (ntpd only requests time updates at its polling interval, which has a maximum value of 1024 seconds). Once verified, inform Ralph and/or the Back Office of the transient nature of the issue and the lack of impact.

    If this is not the case, investigate the NTP cloud and daemon. Consult with Brandon if this becomes problematic.

     

    3. Tools

     

    A. ntpstat

    This command, when run locally, will give output such as the following:
       Synchronized to NTP server (10.60.20.245) at stratum 3
       time correct to within 39ms
       polling server every 1024 s

    This will tell you the server to which ntp is synching, the root dispersion in milliseconds, and the polling interval. If ntp is unsynchronized, the output will say so. For scripting, ntpstat will return "0" if ntp is synchronized, "1" if it is not synchronized, and "2" if ntpd has failed.

    ntpstat can only be run locally. Refer to the <a href="http://linux.die.net/man/1/ntpstat">man page</a> for more information.

     

    B. ntpq

    This command allows you to query both local and remote ntp servers. It provides several options, the most relevant being peer and readvars. Refer to the <a href="http://linux.die.net/man/1/ntpd">man page</a> for more information.

     

    C. ntpdc

    This command provides largely the same information as ntpq, but in a slightly different format. Refer to the <a href="http://linux.die.net/man/1/ntpdc">man page</a> for more information.

     

    D. Meinberg NTP Monitor

    This is a Windows port of ntpd, plus an extremely useful NTP monitoring application. It can be downloaded <a href="http://www.meinberg.de/english/sw/time-server-monitor.htm">here</a>.

    E. NTP Logs

    On servers running the NTP daemon, loglines are written to /var/log/messages. Grep for "ntpd" to see them easily. Of particular note are the following line(s):

     

    • synchronized to 10.60.20.245, stratum 2
      • Indicates that the server switched to this time source, including the time this occurred
    Post edited by Rym on
  • I should also note that this tiny excerpt is almost three years old.
  • Sonic - Check your gmail, I sent over a small PDF for you to have a look at.
  • Thanks again to both of you!
Sign In or Register to comment.