Page 1 of 2 12 LastLast
Results 1 to 15 of 18
  1. #1
    Join Date
    May 2004
    Posts
    56

    Unanswered: Writing sufficient tech. documentation

    (A search on "writing documentation" yielded no results)

    Access XP

    I'm leaving my current position and employer and would like to provide for whoever takes my place good technical documentation. I can print the relationships showing tables, reports regarding fields for each of the numerous tables, and the code from each of the modules (few macros used) but is there anything else that anyone recommends that I prepare/provide or links to sources out there that speak to this subject.

    Thanks in advance for taking the time to reply.

  2. #2
    Join Date
    Sep 2003
    Location
    MI
    Posts
    3,713
    The amount of docs you should leave depends on the person that you'll be replaced with ... Obviously, there is no amount of docs available to help if the replacement is an idiot/numbnut/dipshit/moron ... At a minimum, have docs so that a reasonable programmer can follow your logic ... Even if the replacement is a wet-behind-the-ears novice ...
    Back to Access ... ADO is not the way to go for speed ...

  3. #3
    Join Date
    Feb 2004
    Location
    CT,USA
    Posts
    250
    Hey, did you make flow charts? How about pulling your comments out of the code modules if used? Go to modules export as .bas text files and filter your comments, it may provide a skeleton of sorts to make forgotten flow charts. There is the generic Tools/Analyze/Documenter in access.

    Other than that, your quitting/resigning/moving on let your company pay him to learn on-the-job as we all did.

    PS-- Don't forget to give successor the important links, like to this site!!

  4. #4
    Join Date
    Oct 2004
    Location
    Oxfordshire, UK
    Posts
    89
    Visio could also be used to generate the data object model for your db. Whatever flow chart you come up with, link it into the user documentation (!) so that your successor can work out where data is entered/edited and displayed. If your feeling generous, explain any of the more funky coding with reference to the specific functions and modules.

    Oh, and comment all objects, if you haven't done so already...

  5. #5
    Join Date
    Mar 2003
    Location
    The Bottom of The Barrel
    Posts
    6,102
    Provided Answers: 1
    I use a combination of viso (as mentioned above) charts to indicate flow of control and processing as well as a more traditional "reference manual" containing any custom functions, their compenents and examples of usage.

    I figure if the next guy can't figure it out from there, they probably shouldn't be tinkering with my projects in the first place...
    oh yeah... documentation... I have heard of that.

    *** What Do You Want In The MS Access Forum? ***

  6. #6
    Join Date
    Feb 2004
    Location
    One Flump in One Place
    Posts
    14,912
    Eeeee - what a fun notice period you have in ahead of you

    One thing I think worth emphasising (as MyNewFlavour suggests) is to give a high (app\ class\ module\ function\ proc) level summary of the purpose of any given procedure (by this I mean anything bespoke that you have written yourself) as well as inputs, outputs, expected outcomes, gotchas etc. If you did anything a particular way explain why. If you deliberatly didn't do something a particular way explain why. It will save your successor exclaiming "what's this dipshit done this for????" followed by "oh - now I see why he\ she did that...." and having to roll back 4 hours of "improvements".

    If you have used any unusual or idiosyncratic conventions or application logic then outline them.

    Broadly speaking - much of the above is considered good practice and is a minimum at many coding shops but even the lone developer can benefit from logging their work as they go.
    Testimonial:
    pootle flump
    ur codings are working excelent.

  7. #7
    Join Date
    Sep 2003
    Location
    MI
    Posts
    3,713
    Quote Originally Posted by pootle flump
    Eeeee - what a fun notice period you have in ahead of you

    One thing I think worth emphasising (as MyNewFlavour suggests) is to give a high (app\ class\ module\ function\ proc) level summary of the purpose of any given procedure (by this I mean anything bespoke that you have written yourself) as well as inputs, outputs, expected outcomes, gotchas etc. If you did anything a particular way explain why. If you deliberatly didn't do something a particular way explain why. It will save your successor exclaiming "what's this dipshit done this for????" followed by "oh - now I see why he\ she did that...." and having to roll back 4 hours of "improvements".

    If you have used any unusual or idiosyncratic conventions or application logic then outline them.

    Broadly speaking - much of the above is considered good practice and is a minimum at many coding shops but even the lone developer can benefit from logging their work as they go.

    Personally, I say "SCREW THEM" ... Let them figure it out ... It would take too much time to describe my rationale for my implementation ... They can do with it as they will (including blowing it the hell) ... I ain't working there no mo ...

    Follow my logic or die!

    P.S. - Sugar buzz. WAY to many double-stuffed oreos today ...
    Back to Access ... ADO is not the way to go for speed ...

  8. #8
    Join Date
    Dec 2002
    Location
    Préverenges, Switzerland
    Posts
    3,740
    go for it Mike.

    they replace a coder with a dumbo at 10% of the price and, oh dear, ooops, new guy can't read code and has no idea what a user is or what the application is supposed to do...
    ...SPECIAL PROMOTION: download crocodile tears FREE from www.ugotfu*k**.sad

    that doesn't remove the obligation to add "reasonable" documentation. worst case: you may not get outsourced in time and it might be you who has to decrypt last years spaghetti for this years update

    izy
    currently using SS 2008R2

  9. #9
    Join Date
    Feb 2004
    Location
    One Flump in One Place
    Posts
    14,912
    I think I must just be getting dumber then...

    The amount of time I have spent trying to figure out what the f#@k I was thinking 2 years ago when I wrote some obscure but inspired and, crucially, unannotated code. I wouldn't even want to replace me.

    In fact - of all the people I would least like to have to replace - it's me.
    Testimonial:
    pootle flump
    ur codings are working excelent.

  10. #10
    Join Date
    Sep 2003
    Location
    MI
    Posts
    3,713
    Quote Originally Posted by izyrider
    go for it Mike.

    they replace a coder with a dumbo at 10% of the price and, oh dear, ooops, new guy can't read code and has no idea what a user is or what the application is supposed to do...
    ...SPECIAL PROMOTION: download crocodile tears FREE from www.ugotfu*k**.sad

    that doesn't remove the obligation to add "reasonable" documentation. worst case: you may not get outsourced in time and it might be you who has to decrypt last years spaghetti for this years update

    izy
    Izy,

    I've had to do that ... Like Dan's post, I've had to go into some of my older code and have said "WHAT THE F**K was I thinking???" So, yes. I do a much better job of documenting my code ... I do try to stay away from black magic code if at all possible ... It's a real pain to try to explain what it does when you haven't the foggiest idea ... Makes you look stupid. Nothing like having a Grand Poobah fall from his perch eh?

    Beside that point, I make no real effort to help my replacement understand how stuff works that I wrote unless they're there before I leave to explain it to them ...

    Flowcharts are for sissies ...
    Back to Access ... ADO is not the way to go for speed ...

  11. #11
    Join Date
    Nov 2003
    Posts
    1,487
    Interesting...a topic basically gone typical. It almost makes you want to put new meaning to the words "Job Security", "Indispensable", "Consultation Fees", just to blurb a few.

    Hell...encrypt what you can and run.


    .
    Environment:
    Self Taught In ALL Environments.....And It Shows!


  12. #12
    Join Date
    Nov 2004
    Location
    out on a limb
    Posts
    13,692
    Provided Answers: 59
    In my view: in essence, if you haven't already got good technical docuemntation,then its already to late. You have already failed in the task. Personally I take the view that a lot of the docuemntation should be part of the code - expalking why some dodgy looking piece of code does this or that.
    although the business logic reatins in the business, there are things that you have done or discovered that the company / branch / office does differently - the exceptions need documenting.

    Still, like we all spend lots of time documenting whilst the project is in development (as if). It amazes me the things that I see commented (the classic being a comment to explain what a line does whenif you understand the vb you can read it yourself), the comments that are misleading or not there. the comment should explain why something is done, not neccesarily how it is done.

    The flow charting - great for intial design, not so sure how good it will be for a newcomer.
    I'd rather be riding on the Tiger 800 or the Norton

  13. #13
    Join Date
    Sep 2003
    Location
    MI
    Posts
    3,713
    Quote Originally Posted by CyberLynx
    Interesting...a topic basically gone typical. It almost makes you want to put new meaning to the words "Job Security", "Indispensable", "Consultation Fees", just to blurb a few.

    Hell...encrypt what you can and run.


    .
    Welcome to the club ... The dirty little secret is out ... We don't know what in the hell we're doing ... We make it up as we go and learn from our past mistakes ... Shhh. Don't tell anyone.
    Back to Access ... ADO is not the way to go for speed ...

  14. #14
    Join Date
    May 2004
    Posts
    56
    wow...Wow...I mean WOW! What a flood of comments I got! Interesting & reassuring. Gotta say, some folks allude to actually having the time to flow-chart and document in design or as you go. If that's you, KEEP THAT JOB because I barely have time most days to leave my PC to use the washroom (no kidding!) let alone write some useful documentation. If I wanted to work in an emergency room every day, I'd have become a doctor! (Yes, yes, I know, that's why I'm paid to be here, to fix things, blah, blah, blah.) Sorry...burnout is showing. One of the reasons I'm moving on.

    Finding yet another office in crisis is easy. Finding one that's not, well, there's a beautiful thing. Again, thanks everyone for the input!

  15. #15
    Join Date
    May 2004
    Posts
    56
    (dupe, again. Ugh! Slow networks/systems totally stink!)

Posting Permissions

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