Technical documentation at LinkORB in [#technical-documentation]
Building and maintaining quality technical documentation is an important part of LinkORB’s strategy. Having good technical documentation helps us:
- Onboard new engineers and technical team members
- Get existing engineers working more quickly on applications and technologies they haven’t previously worked on
- Remove “bottlenecks” where only one or a small number of engineers understand an application or technology
- Share technical knowledge and best practices across the organizations to up-leveling everyone’s skills
- Support users of our dozens of open-source repositories
Technical documentation frequently asked questions (FAQs)
What is considered “good” technical documentation?
Good documentation communicates all necessary information in an organized way so that the reader gets the information they need when they need it.
Our goal for the technical documentation library at LinkORB is to create something similar to Digital Ocean’s Learning Community with clear style, structure, and formatting guidelines.
Where is technical documentation stored at LinkORB?
Technical documentation at LinkORB is principally stored in 2 locations.
- LinkORB’s GitHub repositories
- The LinkORB Engineering site (this one!)
Documentation at the repository level should be repository specific - while documentation at the engineering website is not-project or application-specific, but information that is more general or spans multiple projects/repositories.
Who is responsible for technical documentation at LinkORB?
While everyone is responsible for good technical documentation (seriously!), LinkORB does have a dedicated technical writing team.
How are technical writing requests managed at LinkORB?
At LinkORB, “documentation is code”. As such, technical writing requests are managed similarly to engineering requests. Our technical writers and engineers leverage a Team HQ Project to manage the technical writing workflow.
At a high level, the following diagram shows the workflow for completing a technical writing task at LinkORB.
To live our mantra of “documentation is code”, the reader will note that all documentation is reviewed through pull requests and merge operations to one of LinkORB’s GitHub repositories or the LinkORB Engineering site.
Technical documentation standards
Without being overly strict, LinkORB has certain standards for its technical documentation. Standards create clear expectations for technical writers, but also provide consistency and clarity for readers. Please see the following resources to learn about LinkORB’s technical documentation standards:
- Name: Technical Documentation (
#technical-documentation)