This style guide provides editorial guidelines for writing clear and consistent documentation.
Organization of Knowledge Base
This knowledge base is organized into four sections:
- Getting Started - a collection of articles that introduce Admins to VDR with details on how to setup a data room, add users and set basic permissions
- Key Features - a collection of articles covering core functionality of VDR listed in alphabetical order
- Managing Permissions - a collectioin of articles that focus on permissioning, our most critical and complex workflow
- Release Notes - a collection of articles that cover periodic updates and our roadmap
General Guidelines
- Article Excerpts: should be clear, specific and fit on one line.
- Article Ordering: articles should be listed in the order that fits the context. For example, it doesn't make sense to randomly list articles in Key Features given users often have an idea of what they are looking for, so they should be listed in Alphabetical order. When it comes to Release Notes, users care most about what's new, so articles should be listed in reverse chronological order (so the most recent is at the top).
- Article Titles: should be short, specific and reference terminology used in the VDR application
- General Vocabulary: use clear and concise language, err on the side of being less technical, don't be verbose and assume the reader will not understand your acronyms (if they must be used, spell them out somewhere at the beginning of the article, eg "virtual data rooms (VDRs) are used to store information".
- Know your audience and don't assume they are stupid: we don't need an article on how to click a button that says "upload." The user who can't figure that out won't find your article in this knowledge base telling them how to do it.
- Be consistent: the mind looks for patterns. Articles should use consistent language and consistent structure.
- Use headers: the mind looks for short cuts, give readers the ability to scan headers and find what they need quickly.