-
Notifications
You must be signed in to change notification settings - Fork 4
Documentation Standards
Author: Jason E. Gillikin
Approver:
Effective Date: v0, 09-Jan-2021
This document identifies the standards for documentation regarding the Winnie_Bot project. This document is presently an unapproved draft.
Every open-source software project requires clearly defined locations for developer, community, and end-user documentation. This decision document outlines those choices for the Winnie_Bot renovation project.
Documentation standards follow, in alpha order by role:
CORE TEAM. The Core Team (Dawn E. Collett, Jason E. Gillikin, Katie Macke) maintains all documentation for the project and administers the Winnie_Bot Community Server on Discord, using the @Core Team role. Documentation specific to the project as a whole is associated with this Wiki. This Wiki should be considered the first-reference "operating manual" or "telephone directory" of the project, which offers big-picture documentation as well as authoritative pointers to non-Wiki information sources.
DEVELOPERS. Specific tasks for developers reside in a Winnie_Bot Kanban board operated out of a Notion.io account hosted by Dawn E. Collett. Developers may be granted guest access to this board individually by Dawn for the purpose of reviewing and responding to individual tasks within a milestone sprint or across several sprints. Each item in the board lists appropriate RACI roles, dependencies, and acceptance criteria; as developers who are responsible for the task progress in their work, they should document progress within the board and, as needed, hyperlink the relevant GitHub pull request. This Notion account is limited solely to software development activity. The discussion of tasks should occur in the #dev-discussion or #dev-discussion-room channels on the Winnie_Bot Community Server on Discord. Developer work product is pushed to the appropriate code branch as per Katie Macke's direction; all merges are reviewed and approved by a member of the Core Team.
The Core Team elected against using the board function on GitHub, for reasons related to functionality and privacy.
TRANSLATORS. The translators work solely out of the Winnie_Bot Community Server on Discord, through the #translation-strings, #translation-team, and #translation-discussion-room channels. As translators complete their work, they should prepare a file according to published specifications and notify @Core Team on Discord that the file is ready for merging into the project. Once merged, the translation file becomes part of the codebase and that version is considered the sole official copy of the translation strings for a given language. (See Translation Framework for specific guidance.)
TECHNICAL WRITERS. The technical writers who generate end-user documentation work solely out of the Winnie_Bot Community Server on Discord, through the #documentation channel. Documentation uses the mdBook toolkit and pushes to end users through the GitHub Pages system. (See Technical Writer Framework for specific guidance.)
IMPORTANT — The Winnie_Bot Community Server on Discord is not an authorized repository for documentation, although it's the primary mechanism by which all contributors as well as engaged users share bug reports, discuss current tasks, and obtain project updates. Any contributor who seeks to add official documentation to the project but lacks the requisite permissions should reach out to a member of the Core Team for assistance.