“Documentation is one of the most important parts of a software project” – Eric Holscher, co-founder of Write the Docs.
Documentation is official information provided by the company for our users and contributors. It is the preferred method of technical support and should provide instant clarity for many issues.
Within Thoth Tech, all documentation will be written in markdown. You can find the guide here.
Without documentation there is no record of:
- Choices and decisions
- Why functionality is added
- What processes are
- How users use the tool
Consider: As a new recruit to Thoth Tech, wouldn’t you have loved documents on how to install, set up, and contribute to our Products? Or easy to access guidance on what features were to be created, improved, or removed?
The type of document can affect who uses it.
Thus, it is important to think about the intended audience of when writing documentation.
Consider: If a tool is made for primary school children odds are they won’t know what the #FFFFFF coloured button is.
The people who will use Thoth Tech documents are:
- Thoth Tech employees / interns
- Product End Users
- Business Analysts
- Potential Product users
- Outside Contributors
- Process
- QA processes
- CONTRIBUTING.md
- Product
- Technical
- README
- API Documentation
- Release Notes
- System documentation
- Requirement specifications
- Scope
- User Stories
- Business Analysis
- Epics
- User guides / manuals
- How-to guides
- Tutorials
- Troubleshooting
Empower: We want our people to have the knowledge to make the most of our products
Respect: We want our people to feel included and accepted for who they are
Educate: We want to assist our people in their learning and provide them with the information they need
Guide: We want to lead our people in a thoughtful manner towards their goals
Honest: We want to be truthful to our people and focus on our real strengths
- Clear
- Useful
- Friendly
- Appropriate
- Consistent
- Accessible
- Tone:
- causal, yet still formal
- Language:
- Avoid jargon/slang
- Active voice
- Write positively
- Second person
- Titles
- Screenshots and Images
- Delivery Speed
- Focus on the message, use the title as a guide
- Be concise
- Be specific
- Be consistent, formating should mimic the template or style guide
In active voice, the subject of the sentence does the action.
In passive voice, the subject of the sentence has the action done to it.
Yes: Marti logged into the account.
No: The account was logged into by Marti.
One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.
Your account was flagged by our Abuse team.
Someone reading technical content is usually looking to answer a specific question.
We don’t want to overload our audience with unnecessary information, choices, or complex ideas or phrases when we don’t have to.
Guidelines:
- Stay relevant to the title
- Keep headlines and paragraphs short and scannable
- Use second person
- Simplicity and Clarity
- Use Images and Screenshots to assist
We must write for a diverse audience of readers who can interact with our content in different ways.
Consider the following:
- Would this language make sense to someone who doesn’t work here?
- Could someone quickly scan this document and understand the material?
- If someone can’t see the colours, images or video, is the message still clear?
- Is the markup clean and structured?
- Mobile devices with accessibility features are increasingly becoming core communication tools, does this work well on them?
For support with Documentation please refer to:
- Documentation Team
- Area Lead