Results 1 to 17 of 17
  1. #1
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059

    What to expect from a PHP programmer regarding documentation?

    Let's say you hire a PHP programmer for a fairly large programming project. What should you expect from the programmer in terms of documentation? I know that it really helps when a programmer is diligent in properly commenting throughout the files so that others can understand what is going on.

    But besides that, should you expect more in terms of documentation? Should the programmer provide an outline, a proposed infrastructure, a proposed integration, etc. that fully explains the entire project?

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  2. #2
    Join Date
    Feb 2003
    Location
    Connecticut
    Posts
    5,441
    Well, if the programmer is using object-oriented design, they should by default have comments in their code which can be read by PHPDoc. PHPDoc is a program which reads comments in code and automatically converts it to an easy-to-read HTML format.

    Generally the entire project outline and feature list should be decided on beforehand, so between that, comments in the code, and a healthy todo list, that should be enough to go on.

    Additional documentation (i.e. a usage manual) is a nice addition, but for most PHP projects, it isn't worth the time to create one.

  3. #3
    Join Date
    May 2004
    Location
    Toronto, Canada
    Posts
    5,083
    If the project is large enough a design document is pretty much mandatory as is a clear set of Business requirements that everyone agrees on. Failing to do so just results in situations where scope is in question later and many a project has gone wrong due to that.
    André Allen | E: aallen(a)linovus.ca
    Linovus Holdings Inc
    Shared Hosting, Reseller Hosting, VPS, Dedicated Servers & Public Cloud | USA, Canada & UK - 24x7x365 Support

  4. #4
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059
    Aside from overall project goals and feature lists, what about a more detailed description of how it will be coded? For instance, let's say the project calls for integration of a billing script with an API. A programmer has an idea in his mind as to how he will achieve this. Should he storyboard this from the outset? Let's say the original programmer in a project becomes unavailable to finish the project. If a new programmer stepped in, surely it would be helpful to have detailed documentation as to how the original programmer planned to creating that integration. Or is this not the norm?

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  5. #5
    Join Date
    Oct 2002
    Location
    Canada
    Posts
    3,100
    This is what happens in real world.

    Client asks for application with certain set of features and functionality. Often client will just present very rough idea of final product. Based on that programmer will make some kind of storyboard that he/she would follow when realizing the project and that will help him/her estimate time needed to complete the project. Based on this you will get your quote.

    Almost every project can be done in many different ways and based of programmer's perception of your budget this quote will include or not some optional lines. Detailed documentation is the first line to be cut off if your budget is in any way limited. Majority of decent programmers use OOP and comment their code so that programmer of equal or greater skill would have no much problems taking the project over. Writing detailed documentation would seem like asking for more money for nothing to most clients.

    In perfect world this is what would happen.
    You would hire consultant to help you clearly define your project goals. Consultant would, based on his/her assessment, write our storyboard and detail all project deliverables. Technical documentation might be one of them. Consultant would then write RFP which you could send to programmers you want to consider for your project. If you have "technical documentation" listed as one of the deliverables on your RFP, programmers would quote for the time needed to write it, and you would have every right to expect to receive it.

    If you did not go through this process and you did not ask for technical documentation and there is no "technical documentation" line in your quote with dollar amount next to it, you can hope for it, but do not expect it.

  6. #6
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059
    Thanks, Dan, Raul and Sasha! Very good info.

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  7. #7
    Join Date
    Sep 2006
    Location
    Indiana
    Posts
    166
    I agree w/ Sasha.

    If it were me doing the programming, the likelihood of your getting documentation directly correlates to how much you're paying, and inversely correlates to how much scope creep and how much of a pain you are to deal with.

    Of course, if it were specifically quoted to give technical docs, they would be provided per the contract.
    [Lurking Glass] <- Not a webhost.

  8. #8
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059
    Quote Originally Posted by eviltechie View Post
    ... and how much of a pain you are to deal with.
    Ah, so apparently you've worked with me before...

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  9. #9
    Join Date
    Jul 2003
    Location
    Kuwait
    Posts
    5,099
    Hey Vito -- long time (this is fyrestrtr btw).

    I always ask for the following, and on a complicated project the first and the last are a must.

    1. E-R Diagram
    2. Data Dictionary
    3. Use Case Diagrams

    This generally gives me an idea if the programmer has any actual programming experience or just one of those script kids that is out to learn as they burn you down; because usually they won't know what you just asked for.

    Also, a SRS (Systems Requirement Specification) which is based from a technical RFP/RFQ is also handy as an overall guide and also for you as a client to know what it is that they (the developers) will deliver. The SRS is basically the technical document that defines what you'll be getting, based on your request (RFQ/RFP).

    When you have to argue your point or want to steer the project in the right direction; or to avoid 'scope creep', the SRS comes in very handy.

    Of course, the other stuff (contract, NDAs, etc.) are also required.

    I also have them sign a separate rights release document; and also make it a condition on their contracts that any third party libraries must be suitably licensed for commercial use, and if they intend to use a library that requires a separate license; then that falls under a separate contract/agreement. This avoids the issue where your program does what you want; but you end up getting sued because you are using some control/library that is not licensed correctly for your purpose.
    In order to understand recursion, one must first understand recursion.
    If you feel like it, you can read my blog
    Signal > Noise

  10. #10
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059
    Hey, fyrestrtr, yes it has been a long time.

    Thanks for the great post. Plenty of good advice.

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  11. #11
    Join Date
    Sep 2006
    Location
    Indiana
    Posts
    166
    Quote Originally Posted by vito View Post
    Ah, so apparently you've worked with me before...

    Vito
    Haha! No, was just saying in general...the harder the client is to deal with the less inclined I am to provide anything not specifically spelled-out in the contract...or provide anything free of charge.

    For example, I have some clients that are easy to work with, pay on time, etc...and in return they get priority, and some perks like not getting charged for meetings, corresponsence, or little things that take me less than 10 minutes. Conversely, I have a few clients who a very demanding, take a long time to pay, need a lot of hand holding, etc...they get lowest priority, no perks, nothing extra at all.
    [Lurking Glass] <- Not a webhost.

  12. #12
    Join Date
    Nov 2006
    Location
    College Station, TX
    Posts
    185
    Are you talking USER technical documentation, or are you talking PROGRAMMER technical documentation?

    Most of the projects I work on are fairly 'small' -- call it a month or two of coding time at most.

    My clients generally provide me with a list of tasks they want the code to accomplish. This is a simplified form of a functional requirements document. Before I start coding, I return a set of wireframes in PDF form that the customer reviews to get an idea of how the tasks they want to accomplish will look to them. This is a simpler form of a functional specification.

    Generally, I provide a PDF 'book' with step by step instructions detailing how to do things that the customer seemed to be stuck on -- more of a 'recipe book'. Ideally my design is simple enough to give a user a clear path to accomplish all of the requested task flows... making a manual un-necessary. Since we've focused on process and flow from the very beginning, there's usually the interface equivalent of very bright flashing lights saying "CLICK HERE NEXT", and a lot of validation behind the scenes.

    For technical documentation, I use 99% inline code. That's the first place most programmers (who are impatient beasts) are going to look anyway. I also try to make my code as readable as possible, and I try to use frameworks that keep things in places that are familiar to other programmers used to those frameworks... Zend Framework, Symfony, CakePHP, and (gak)Fusebox are a few of the ones I've used. That way, any programmer who knows the subset of the PHP technology that's used with each of those frameworks will be able to 'jump right in' and know where to look to fix a particular bug or accomplish a particular task.

  13. #13
    Join Date
    Jan 2002
    Location
    Toronto, Canada
    Posts
    11,059
    Karl, in this case, I'm talking about programmer technical information. I'm just wondering how a programmer needs to set up a project so that if the original programmer needs to be replaced mid project, a new programmer can step in and logically assimilate into the project with the help of well documented assistance.

    Vito
    DemoDemo.com - Flash tutorials since 2002
    DemoWolf.com - 5,300+ Flash tutorials for hosting companies, incl. Voice tutorials

  14. #14
    Join Date
    Jul 2006
    Location
    Nova Scotia Canada!
    Posts
    783
    The most successful projects I've worked on have a phase in the beginning specifically dedicated to requirements definition. As many have mentioned, solid requirements beget efficient projects. Documentation can take a long time to write so the requirement for it, and what level, should be defined at the onset along with the actual technical requirements. That's the only way everyone will get what they want.

    Sadly, as some have also mentioned, documentation is the first thing to go when the budget lines start to be approached. The vast majority of PHP projects these days are performed off of sites like Rent A Coder where the buyers are generally unwilling to pay for anything that they don't have to. Although, to be fair, I have participated in several requirements definition projects off of RAC, but they are few and far between.

    I don't think anyone should be pondering "what to expect" in terms of documentation or otherwise within a project. All that says to me is that requirements for that were not agreed upon in the beginning. Rather, it makes more sense to decide what you want and work them into the requirements so everyone knows that there is a deliverable there.

  15. #15
    Join Date
    Sep 2006
    Location
    Indiana
    Posts
    166
    Ya know, as far as documentation goes. It might make sense to reverse the order things are done. Make the client provide full written documentation, then just build something that makes what they've written true.
    [Lurking Glass] <- Not a webhost.

  16. #16
    Join Date
    Jul 2006
    Location
    Nova Scotia Canada!
    Posts
    783
    That would be great if clients were able to enunciate what they want

  17. #17
    Join Date
    Aug 2007
    Location
    West Chester, OH USA
    Posts
    92
    Another thing to keep in mind is that very few clients are ever happy with the *true* amount of time it takes to develop AND document a large project. Often, programmers are pushed very hard to make unreasonable deadlines. When this happens, something has to give, and usually documentation is the first thing to get scrapped.

    Programmers are human, so if you want good documentation make sure you specify that and then follow up accordingly by providing a reasonable amount of time for the developer to write documentation.
    Tu ne cede malis, sed contra audentior ito.

Posting Permissions

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