I develop software, and by extension write a lot of text intended for another person, ranging from on-screen labels, full-blown user manuals, FAQs, tips, e-mails, even comments in code. Having to write means that when I read, I do so with a critical eye.I'm not qualified to give a complete overview of writing styles for different situations, but I can tell you one thing I hate wherever I read it: anthropomorphism.Anthropomorphism is making something human (see the Wikipedia definition here) - for example, the way help text is presented using the Office Assistant (Clippy). Any text that describes a non-human...

I've always had a problem with documentation. I agree it's absolutely necessary; it's just often the requirements for documentation are so vague that I never know if I'm done or not. One way to enforce standards when documenting tables and views in SQL Server is by using extended properties and auto-generating the documentation. I've used many free tools to do exactly this over the years; currently I favour SQLSpec. If you're interested in a cheap, do-it-yourself method of documenting SQL Server databases, check out this article titled "Create a SQL Server Data Dictionary in Seconds using Extended Properties" at MSSQLTips. Although...

In the continuing battle over database documentation, Jon Galloway has released a new .NET 2.0 weapon (with source!): Data Dictionary Creator Data Dictionary Creator collects extended properties/descriptions for SQL Server tables and columns and outputs the resulting documentation to a variety of formats. It's also easy to use, and did I mention the source is downloadable too? A tool I've used in the past for retroactively adding extended properties to views, stored procedures, and stored procedure parameters is the no-longer available XpressProps. Nowadays, I add extended properties to both the procedure and all parameters while scripting the object creation - here's some script...