SitePoint Sponsor

User Tag List

Results 1 to 3 of 3
  1. #1
    SitePoint Member
    Join Date
    Dec 2007
    Location
    Utah
    Posts
    7
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Website documentation template

    I've just finished a few internal sites, and I need to write the documentation for them. Does anyone have a website documentation template they use or suggestions on content areas? Thanks, in advance, for any help!
    Last edited by mvivit; Sep 2, 2008 at 12:10. Reason: Subject/verb agreement is nice. <g>

  2. #2
    SitePoint Enthusiast
    Join Date
    Aug 2008
    Posts
    31
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Depends what you mean on documentation. Do your comments within the scripts perform any functional documentation?

    OK, I have my own 'how it all works' files that I create as I go, typically a copy of the script in coloured print (on a PC? use Programmers Notepad to code) including line numbers, comments etc. With at least a one page explanation of what (and why) this script does what is does. If there are graphical elements used, I generally have a printout of them with filename on a page (or two) and a brief description of what they do. Each script has a header area (even if it only performs a simple function like repetitive close and open divs - I have a file that closes a div with a comment and opens the next with an id for example, it's three lines of PHP with 32 lines of header comment). This header has last edit date, version number, author etc. If I leave this will be then updated by the next guy or gal.

    A typical website I maintain will have three or four main public files (index.php, sections.php, articles.php, user.php) with various includes to control what each does. I would guess at around 50 php scripts running a site with an average of 5000 URL's, the main site I deal with has 25,000 possible URL's with the same 50 basic scripts controlling it.

    Each file should be fully commented, documented, version tracked and backed up. I have a corporate server with files, a memory stick and my own machines with same copies on top of the web stored version, so if my house burns down on the same night as my webhost is destroyed in an earthquake the company can be back online in the morning.

    This is all fully explained in the documentation that is created.

    Problems. If you are more than a one man band, you rely on the other people to maintain this system.

    In February I upgraded a suite of sites which all relied on a unique .htaccess file. Foreseeing problems I suggested a changelog be maintained on the server.

    Seeing the changelog had no updates since my last version I uploaded a new copy one time which brought down several sections of a site.

    Now I have reworked this so that the exact same .htaccess file can be installed on any site and do what it says on the tin.

    But at the end of the day my point is that your documentation can only be as good as your updating of it.

  3. #3
    SitePoint Member
    Join Date
    Dec 2007
    Location
    Utah
    Posts
    7
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Thanks for the reply, Hugh. Sounds like you have a great system going. I use Oracle Portal at work, and a lot of what I do is within that system and doesn't "live" in separate files. My separate files (.js, .css, .sql, etc.) are documented within the file. Because the Portal components are sometimes difficult to access, I usually create a separate document describing colors/branding and their usage, region location and attributes, Portal page templates, and UI templates.

    I have a basic template, but was just curious about what other designers do.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •