-
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.
Each community has a banner containing its name and optional graphic elements. This banner appears on every page on that community's site. Communities can make certain customizations (see below).
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 numbers of upvotes and downvotes
- for each post, access to the feedback feature (to be further specified separately)
- (see also: affordances for questions, answers, and tag descriptions)
Answer order on a question page is determined by score. Score is derived from votes (see "Votes and Scores"). Scores are not visible in the default UI.
- 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: subset of CommonMark for feedback (comments).)
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 and can also add 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.
All pages that present lists (question list, list of users, list of tags, lists on profile pages, etc) use pagination.
User login and account creation will be specified separately.
Each user has a unique user ID and a profile page. The unique ID is always tied to the user, regardless of changes to display name. The profile page includes a display name (defaults to user ID) and an "about me" area (defaults to empty), both of which can be edited by the user. The "about me" text has an edit history. The profile page displays (non-editable) links to the user's posts, preferably with pagination.
There is a way for a user to associate an account on the corresponding Stack Exchange site for purposes of claiming imported content.
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, complex search, and/or/not.
Codidact will provide static help content (for now) and static page-footer content.
A way to hold meta discussions exists and is visible.
For each answer we display raw upvotes and downvotes. This makes controversy visible.
For each answer we compute a score thus: (upvotes + bonus + N) / (upvotes + downvotes + bonus + 2N). Scores are not directly displayed. Default N is 1 but is configurable per-site.
We order answers by score, with newer answers winning ties.
For questions older than (default) 6 months, new answers are labeled “new” and given a bonus in the scoring formula for the first (default) 7 days. This allows new answers to have more visibility when there are high-scoring answers present already. The amount of the bonus is TBD. All values are configurable per-site, including turning this feature off.
(Early, but not required for MVP): a user, after voting, can choose to make that vote public. People viewing the answer can see that there were N public upvotes and M public downvotes, take some action to see who they came from, and decide how to weigh those people’s opinions.
(Source)
Each community can customize the following items.
- URL (within the instance naming scheme)
- banner graphic
- color set and CSS
- custom static notifications (like the professional-service disclaimers on some SE sites)
We aspire to other customizations post-MVP.
Revised proposal: for MVP, a method exists for a community to import data from its corresponding SE community in a license-compliant way. It is up to the community to decide whether and how to use this; a community might decide to start fresh, import selectively, or import everything and continue operations here. A manual, one-time operation meets the need.
License-compliant could mean importing only data that predates the latest questionable license change, or could mean applying different licenses to pieces of content based on last-write date on SE.
(source)
Other specs alluded to here that need to be written:
- feedback
- rate limits
- user login and account creation
- meta
- runtime environment (what does an instance need)