When to Document
Documentation should be created on a just-in-time (JIT) manner when you need it, and only if you need it. You should document something only when it has stabilized, otherwise you will be updating it endlessly as the situation changes. This is one of several reasons why it proves foolish to write comprehensive requirements documentation early in the system lifecycle—because your stakeholders will change their minds, usually for completely valid reasons, you discover that the investment in detailed documentation was counter-productive. The implication is that detailed documentation should be written after, or at least towards the end of, the development work. Yes, you likely need to do some very high-level modeling to think things through, but investing in detailed documentation too early is questionable at best. I present a critical examination of the big-requirements up front (BRUF) approach at www.agilemodeling.com/essays/examiningBRUF.htm.
Agile Modeling (AM) advises that you should update documentation only "when it hurts". People are flexible, if the documentation isn't perfect that's okay, they can figure it out. Millions of software systems are successfully running around the world as you read this paragraph, and how many do you honestly think have perfect documentation that is up to date and fully consistent? Perhaps a handful? How many billions of dollars, if not trillions, do you think has been wasted over the decades striving to produce perfect documentation? Your goal should be to produce documentation that is good enough for the situation at hand—once it's good enough any more investment in it is clearly a waste.
