If you are writing a letter to your mother, it is fine to create a new a new blank document, type your random thoughts, add highlighting, colors and emphasized text where you want to make and get a point across, and basically format the document with any creative ideas that you feel appropriate.
When working with documents in the workplace, ad hoc formatting is probably not appropriate. Yet I see so many requirements and other technical documents that were written by people who thought that they were writing a letter to their parents.
Imagine if every programmer on the development team wrote source code using their own personal coding standards. Nobody would be able to maintain someone else’s code. It should be the same with documentation. Every document should be written from a predefined document template that includes documentation standards (instructions for use), a consistent set of styles and properties.
The problem not only applies to textual documents, but also to diagrams. UML for example, defines a set of artifacts in terms of a set semantics and rules that apply to that artifact. (As far as I am aware) the icons used to represent an artifact are not defined within UML standards. Not only that, but UML allows the stereotyping of defined artifacts, which in turn leads to a customized representation of the artifact.
An example, I might be, using an arrowhead to indicate the initiator of a use case (which I do), and someone else using a dashed line to indicate the same thing. Now there needs to be an explanation in each document of the meaning of which notation that is being used. Not only that, but if both diagrams contribute to the same document, you are going to confuse your readers.
Use a set of rules for identifying a particular meaning on a diagram. If there is no rule for it, then make one up and explain what the particular notation means (although the more project rules there are , the less explanation needs to be added to the diagram or document). Say for example, you wish to highlight parts of a diagram to indicate that they are candidates for change, but there are no project specific rules for indicating how to highlight changing components. Then go ahead and shade the items (or whatever highlight you prefer) and explain what the highlighting means.
Which leads me to; the number of times I see a figure in a document without, not just a description of the figure, but not even a reference to it. Why did you put this figure here, if you are making no reference to it?
If there are 2 ways of doing something, pick one that works, describe it and stick with it for the length of the project.
Editor's Note: Check out the list of all related best practices.