continuous learning …

To minimize the risk, to deliver a successful project, teams look for a methodology that they can rely on. Most of the development methodologies started with the idea of manufacturing systems: “X delivers high quality, efficient and excellent products applying Y methodology, why we can’t?”
X is one of Japanese companies, and Y is applied on assembly line. But since, we can convert a developer into a computer, we can apply the same logic, can’t we?
Both have project plans, design and production phases. Both have quality assurance, and apply TQM principles.
They should have budget, risk analysis and decision phases…
However, software projects have unique products per projects, where manufacturing companies are producing same lego pieces. Once they have a specification, all lego pieces can interact with each other, and can produce millions of them…Once you have a specification for a part, you produce it, and that’s all, reusable code can be consumed for the new project, but probably they will pick a new language/technology and will not use it, since production of a piece takes three months up to three years… 
I can’t make generalizations because there are trillions of parameters around this subject.  But I had a training on a new methodology last week. [It was an iterative and incremental methodology developed for company].
To be able to outsource, that put planning, analysis and design phases into iterative cycles, and finished the iteration with implementation. The model/documentation that will be handed to outsources can’t set into stone. To make risk analysis perfectly, you can’t assume during development any risks will not arise, and the analysis should not be reviewed.  Throughout all my development experience, I did not have any project changing requirements, changing scope/analysis after all planning phases finishes. But then, it was upto developers to ask questions and contribute to the depth/quality of the delivery.  If you are going to outsource, and trying to perfect your documentation, i.e. every piece of code developers are going to write is in [uml] documents, you can’t expect outsourced developers not to ask questions and change your analysis documents.
Waterfall was not useful, since it was set into stone assuming all phases will be done one by one without review/update.
Iterative and incremental process was not useful, since it was helping with the outputs/artifacts.
However, I am not happy with this model as well since it is a spiral model without any implementation cycle.

If a new framework is developed in your company, and you are going to use it, without proper documentation you can face lots of difficulties. It may company culture “to go and ask questions” but it can be a pain after five questions [ten maybe?]

With defensive programming, and agile methodologies around, lots of developers write their unit tests, created their exceptions carefully, every piece of code is in UML diagrams [object and sequence models,…] but unless it is a culture, nobody creates comments in their code.

Some does, but this becomes more confusing since there is no standard, a few people apply their own standards…

From the very beginning of the .NET [and C#], <summary> tags are there for documentation…This time, I will give  some examples how to use it. 

namespace  EC.Domain.ProductDMgr{ 
/// <summary>  
/// Product Data Transfer Object  
/// </summary> 
public class ProductDTO{ 

  private readonly int prodId; 
  private readonly string title;  private readonly int dissection; 
  /// <summary> 
   /// ProdId is the product Identifier 
  /// </summary> 
  public int ProdId { get { return prodId; } } 
  /// <summary>Title is the title of the product</summary> 
  public string Title { get { return title; } } 
  /// <summary> Dissection is the department of the product </summary>  
  public int Dissection { get { return dissection; } } 
  /// <summary>   
  /// The constructor of the product with identifier and title 
  /// </summary> 
  /// <param name=”prodId”>Identifier of the product</param> 
  /// <param name=”title”>Title of the product</param> 
  /// <param name=”dissection”>Dissection of the product in the store</param> 
  /// <exception cref=”ArgumentOutOfRangeException”> Exception for Dissection bigger than 999</exception>  
  public ProductDTO(int prodId, string title, int dissection) 
  this.prodId = prodId; 
  this.title = title; 
    if (dissection > 999)
        throw new ArgumentOutOfRangeException(“dissection”, “Dissection should be equal or less than 999”); 
    else
    { 
         this.dissection = dissection;
     } 
  } 
}
Anyone  using your assembly should be more confident about the objects and parameters now:

And during the development, that will add extra mile speed to the project:

For detailed info, you may refer to msdn.

There are codeplex projects [SandCastle, AjaxDoc] running on to extend this documentation and create msdn like help documents/websites.