-
Notifications
You must be signed in to change notification settings - Fork 7
Functional Specification
Draft in progress.
Codidact is a web-based Q&A platform with similarities to Stack Exchange. A Codidact instance (a "network") hosts one or more communities (or "sites"). A community has a topic area, which might be broader (like programming) or narrower (like chess). Decisions about community content and governance will be resolved separately; the functional spec focuses on platform capabilities.
A community has the following kinds of content:
- Questions, which must have one or more tags (which link to tag descriptions). Intentionally omitted: question score.
- Answers, which are attached to (and responses to) questions. Answers are sorted based on scores to place the most-supported answers at the top.
- Feedback, which can be attached to questions or answers.
- Tag descriptions, one per tag, containing a short summary and an optional longer description.
- User profiles, which provide access to all of a user's activity in that community and may contain personalization. A user's questions, answers, and feedback link to the user profile.
- Question lists, to enable browsing and seeing updates. As with Stack Exchange, a user visiting the site sees a reverse-chronological list of questions with recent activity. Other sorting options are planned.
- A place for meta discussion. (This could be a special post type on the main site as opposed to a separate site -- TBD.)
(There will be additional types of content in the future. This list is for the MVP.)
To participate, a user must have and log into an account. Core user actions include asking questions, answering questions, providing feedback, voting, and editing questions, answers, and tag descriptions. Some actions are restricted until a user earns corresponding privileges. Privileges are earned through community activity.
Communities have moderators, who can act on any community content including deleting material. All deletions are soft, both to allow undeletion and for auditing. Moderators are able to respond to flags on content raised by users. Moderators can temporarily restrict a user's specific privileges (for example, removing the ability to provide feedback for a day). Moderators do not (at this time) have access to PII.
A Codidact instance has administrators, who have access to PII when needed and can take actions that moderators cannot take (such as investigating sockpuppets).
Subsections (or sub-pages, as needed) will develop these functional areas in more detail.
Each community has a URL of the form community-name.instance-name.TLD.
Each community has a banner containing its name and optional graphic elements. This banner appears on every page on that community's site. Each community can customize its color set and CSS.
The following are available on every page of a community:
- help
- login controls: sign in / register (if logged out), sign out (if logged in)
- link to current user's profile (if logged in)
- link to question list
- ask question
- search
- "the usual footer stuff", TBD (legal, contact, etc)
The question list presents, as the name implies, a list of questions that have been asked. Each item in the list shows the title of the question, its tags, and how many answers it has. The title links to the question page and each tag links to its tag page. By default questions are presented in reverse-chronological order of last modification time. (In the future other ways of sorting and filtering will be possible.) The view presents a reasonably-sized list of questions and provides a way to see more.
- Intentionally omitted: question score, pending decisions about whether/how questions are scored.
An individual question page shows:
- in the question section: title, full question text, tags (as links), user name/link for the asker, timestamp
- all answers with user name/link for their authors, timestamps, and answer scores
- for each post, access to the feedback feature (to be further specified separately)
- for each post, a way to edit and a way to see edit history with timestamps
Answer order on a question page is determined by score. Score is derived from votes in a manner to be determined (and specified separately).
- Intentionally omitted: anything about accepted answers.
A tag page shows the name of the tag, its short description (if present), its long description (if present), and a list of questions using that tag. (Ordered how? Assume filters are not MVP.)
A list of all tags with their short descriptions and links to tag pages is available. (And needs to be linked somewhere appropriate.)
The "ask question" page allows a logged-in user to enter a question title, body, and tags, all of which are required. (For restrictions on asking, see "privileges" and "rate limits" when they're written.) An anonymous user visiting this page is prompted to log in or create an account.
Question bodies, answers, and tag descriptions use CommonMark. When creating or editing them, users have access to a preview of the rendered content. (TBD: CommonMark for feedback (comments) too? No preview, presumably.)
Questions, answers, and tag descriptions have affordances for the following:
- edit (interacts with privileges)
- show edit history
- flag
When flagging content, a user chooses a flag reason from a list or types custom text. Flags are shown to moderators. For flag-handling, see the moderation specification. In the future, communities will be able to customize the built-in flag reasons.
User login and account creation will be specified separately.
Search allows a user to enter text and/or tag names. A search containing a tag name returns only results using that tag. Questions and answers are searchable. (TBD: feedback too?)
- Intentionally not addressed: order of search results.
Codidact will provide static help content (for now) and static page-footer content.
A way to hold meta discussions exists and is visible.
Other specs alluded to here that need to be written:
- feedback
- privileges
- rate limits
- user login and account creation
- user profile (page, editing, required info)
- moderation
- votes and scores
- meta