Documentation and samples

Topics: CAB & Smart Client Software Factory
Oct 6, 2006 at 9:52 AM
originally posted by: askew

I'd steer new users to Eugenio's blog:
Oct 6, 2006 at 10:56 PM
originally posted by: dondi

I think that the documentation and samples provided in the SCSF leave a lot to be desired. The code samples AppraiserWorkbench and BankBranchWorkbench do not contain any class or method comments, let alone inline comments that might enlighten the typical readers - developers that needs to fully understand the reasons behind a piece of code, as they'll need to create similar implementations, not copy-paste it in their own code. The code is neither that self-documenting nor that simple and clear to justify this.

Also, the documentation only covers the basic concepts - I often found myself in a loop going over and over to the same few paragraphs in the documentation when trying to grasp a particular concept.

For me, this made the process of understanding the SCSF a lot more difficult than it needed to be. Looking back on the time I spent getting familiar with the technology, this is the main reason I wouldn't recommend developers to consider embracing it unless a member of their team has already gone through this process and can provide help whenever the docs and samples are not enough.

As a suggestion - if any time will be spent on improving the docs & samples in the future - I found that a model that really helps me understand a specific programming concept was the one used in the Head First Design Patterns book, by Elisabeth Freeman & Bert Bates - code samples are placed side-by-side with comments that explain the intent of the code and the way theoretical concepts are implemented. Maybe someone will consider a similar approach for scsf.