Adsata Documentation System
Adsata's documentation is built using Docusaurus. Docusaurus allows us to build a website for our software and documentation for it.
We use types for our documentation content. We define three 2 primary types and 2 secondary types:
In general, each folder in our docset contains documentation for those 4 types. Our folder structure:
Each Concept page refers to at least one Task page. For example, a Concept with the title Calibration refers to a Task Calibrating the eyetracking software.
However, we also link documentation types to different pages. This is important because it helps us document the software page by page, task by task, and also helps us introduce new concepts.
In order to link Tasks and Concepts to Pages, we use Tags.
Guides and Get Started are not related to any other type, nor do they require Tags.
A get started page is a set of steps to help a user to understand how to use the documentation and/or information on where to get started with Adsata features.
A task gives instructions for how to complete a procedure on Adsata. The procedures should be clear and concise. Tasks will be sorted randomly.
If there are several tasks on a page that share prerequisites, we use the title Prerequisites, and link to it.
A concept introduces a single feature or concept.
A concept answers the questions:
- What is this?
- Why would I use it?
We try to explain concepts as someone might want to know a concept if they’ve never heard of it before.
Concepts don't tell how to do something. They tell what something is.
Each concept is about one concept only.
A guide is an end-to-end walkthrough of a complex workflow or scenario. In general, guides are used when:
- The workflow requires a number of sequential steps where each step consists of sub-steps.
- The steps cover a variety of Adsata features or third-party tools.
Guides are learning aids that complement our core documentation. They do not introduce new features.