-
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).
- 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 (comments), which can be attached to questions or answers.
- Tag descriptions, one per tag (short text, not a full wiki like on SE).
- 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.
(There will be additional types of content in the future. This list is for the MVP.)
A site has customizable categories. A category has a list of posts (like the main questions list) and clear navigation in/out. (One implementation would be "tabs" on the main site for "main", "meta", "blog", etc.) Meta is a category, not a separate post type.
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. (More about URLs coming soon)
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)
- links to all categories -- main question list, meta, and any others
- 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, its votes (up/down), 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.
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), and a list of questions using that tag in an unspecified order. (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.)
Proposed: tag descriptions have the same markdown and length limitations as comments (so you can have links but the text is still fairly short).
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 and answers have affordances for the following:
- edit (interacts with privileges)
- show edit history
- flag
(TBD: how tag descriptions get created/edited.)
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 editable by moderators, and static page-footer content editable by instance admins.
For each question and 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.
Not MVP: 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.
Not 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)
Questions and answers can have comments.
Comments are threaded. There is a way to see what a reply is a reply to, and there is a way to reply to an existing comment.
A maximum of TBD number of comments is shown by default. If there are too many comments to show, priority is given to comments that begin threads (with an indicator that there are more, e.g. "(N replies)" after the comment text).
Comments support a subset of CommonMark to be specified. (Basic text formatting yes, tables and embedded images no...)
Comment use cases (includes muting notifications on your post/thread and archiving threads)
All posts that are not locked (locks are not MVP) can be edited.
Authors can edit freely. Users with the appropriate trust level can edit freely. Users below that trust level can suggest edits.
All edits use the same affordance ("edit" link or whatever) and interface, except that users who cannot edit directly are told the edit will be reviewed before starting and get a notification of pending review on submission.
The author of a post receives a notification of a pending or direct edit.
If there is a pending edit on a post, the post shows an indication of this fact. Users with the trust level to edit can review pending edits. The author can also review a pending edit. Reviewers can accept or reject.
-
Not doing "...and edit" / "...and improve" -- if you want to edit after an edit, then add another edit.
-
How many approvals are needed, from reviewers other than the author? Don't say two just because SE does; what's the right number?
-
Intentionally omitted: edit review queue. We don't have review requirements for MVP. We'll need some way to surface pending edits, but it doesn't have to be a review queue. Maybe there's just a list of links to posts with pending edits available?
Users can flag posts and comments. For MVP they get a textbox. Post-MVP there will be built-in flag reasons (customizable).
Users with the ability to handle flags see an indication of a flag alongside the content and can accept or dismiss it.
Moderators have access to a list of all pending flags.
Questions can be closed if there is some problem that prevents answering them. (Need to find the forum post that proposes short list of close reasons.)
Closed questions can be reopened.
In both cases, a voting affordance on the question is available to users with the appropriate trust level.
TBD: Number of votes needed to take action.
TBD: messaging to author of the question.
The author receives a notification if a question is closed or reopened.
Duplicate, close, and reopen use cases
Draft functional spec for duplicates and hold votes
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:
- rate limits
- user login and account creation (we will host our own instance of some off-the-shelf authentication thing)
- runtime environment (what does an instance need)