Antipatterns

Slide Decks as Documentation

Giving out slide decks as documentation is an antipattern but one followed too often by too many.

Slide Deck best practices include providing concise, bulleted lists that an audience can read without becoming so distracted they don’t listen to the speaker and speakers providing most of the information. A slide deck without the speaker is often uninformative.

Conversely, a slide deck that provides enough information for someone to understand it without the speaker is not a good slide deck.

Slide decks should be used for presentations and that is all.

Videos as Documentation

Videos help convey a steady stream of information. They can hold an immense amount of information but, like a book, require users to consume the entire video to find one piece of desired information. As we would not ask someone to read a book in search of information, asking them to watch a video is also not good documentation practice.

There is a pattern at companies of recording meetings so they can be watched later - most videos go unwatched. It woudl be far better to put in the effort to take minutes during the meeting and summarize the information.

Exceptions

Videos could be used as documentation if and only if the following conditions are met:

1. There is an index listing the different time and topics
2. The audio has been converted to text that is searchable
3. The video recording is adequately supported by additional documentation

Long Pages

Documentation pages should not get excessive in length. Similar to a codebase, when the material gets too long, it is important to encapsulate and organize.