Functional spec begun: please review

Codidact Platform Ideas
1

I have begun a functional specification for MVP based on the requirements we’ve collected so far. The spec is not complete; many pieces await elaboration and some await resolution of discussions here on the forum.

Please take a look at what we have so far and reply on this thread with feedback. Questions to ask yourself when reading include:

  • Is that what I think we meant?
  • What’s missing that hasn’t been explicitly noted as missing?
  • As a front-end developer, do I have enough information to proceed to a design (for the parts that are specified)?
  • As a database designer, do I have enough information to proceed on a schema (ditto)?
  • As a back-end developer, do I see anything that raises alarms (performance, number of server calls, etc)?
7 Likes
3

I’m 95% sure that soft deletion isn’t good enough for COPPA compliance. I’d have to look it up. If the site is run by a non-profit, COPPA doesn’t usually apply, so that might not be an issue for MVP. Someone who knows the GDPR would have to check if soft deletion is good enough for that.

2 Likes
4

GDPR does not apply to posts, only to personal information (although if there’s personal information in posts, we’d need to redact it).

COPPA is a separate thing. As the spec says, we should soft-delete in the vast majority of cases. We will, however, handle legal requests (including COPPA compliance and GDPR) separately, and these will often involve hard-deletions.

5 Likes
5

Concerning meta discussion:

Isn’t that just going to be another instance/network? Or are we planning on doing additional features for that?

Even more so, it seems most intuitive to me to start out with a meta.
For all of Codidact (like meta stack exchange), where we can start voting on stuff while working toward more public releases (“real” instances), fixing some “teething problems”. So MVP - or to be more clear, “public release” - would be just creating another instance/network, but with the issues we found in the mean time fixed of course.

I’m not in the loop concerning the current plans about this though.

1 Like
6

An instance is a collection of sites. Each of those sites needs to have a place to have its meta discussions (scope, why was this question handled this way, should we merge these tags, etc). An instance probably needs a place to have instance-wide meta stuff, since each instance is free to set its own policies and stuff.

Then there’s the Codidact project itself, which needs a place to discuss changes to the platform and stuff like we’re discussing here on this forum. Presumably bugs and well-formed, complete feature requests go to GitHub bug-tracking, but there also needs to be a place to work stuff out and discuss stuff. I don’t know whether that’s this forum, something on Github, or what.

The Codidact platform is different from Codidact instances, though we expect this team to stand up an instance on top of the platform.

3 Likes
7

After reading the entire specification draft carefully and visualizing everything in my mind, I have only a few things to comment or request clarifications about.

First of all: great work! The set of spec overviews is extremely helpful and written clearly overall.

Now, my points:

  1. Why are question scores intentionally ommited? Are questions not going to be voted on / has there been any sort of disagreement regarding that?

  2. Any reason why CommonMark was suggested specifically? (this is not a biased question - I don’t oppose to the suggestion/choice at all, just curious.)

  3. “CommonMark for feedback (comments) too?” - depending on the format of the feedback/comment posts, only a strict subset is feasible to support. (leave it as TBD for now)

  4. I’d like to suggest changing the “When flagging content (…)” section to: “When flagging content, a user chooses a flag reason from a list and types custom text”, instead of “or”.

  5. “Each user has a unique user number and a profile page. The profile page includes a display name (defaults to user number). (…)”: Is it important if the numbers are sequential or not?

Finally, if it would be possible to link to forum discussions from the specs page in the Wiki, as references, that could prove quite helpful during the upcoming months.

Thanks!

2 Likes
8

While I am reasonably certain that comments will support fewer Markdown features than Q/A, e.g., images, I hope that comments can be a little more “full featured” than in SE, and definitely should have “live preview” like Q/A so that you can at least know what features are supported as you type.

Does it matter what the number “means”? No, not at all. So implementation simplicity wins - which means that default User ID is “User” (or whatever) + “unique id from user table”. Which is automatically sequential but may not be obviously sequential since as users change to “real” User IDs, their numbers will end up being gaps in the sequence.

3 Likes
9

Sequential IDs require an integer data type, where sometimes it makes sense to use a GUID type for identities at the DB level. Other than that, sequential IDs “leak” information, and this can sometimes matter - or not.

3 Likes
10

Thanks for the feedback!

I remember some discussion about the value of question votes with no consensus, but it was a while ago. I left it out because I didn’t know, not because I think the answer is “no”. Let’s figure out (on a separate thread) whether to do this and then update the spec.

There was apparent consensus in a thread linked from the requirements.

Agreed. We need bold/italics/pre and links at least, and at the other extreme, comments needn’t support tables. In between, I don’t know. TBD is fine.

Does a spam flag require elaboration? I was thinking that we could bake in “obvious” flags and anything else requires user text.

What’s important is uniqueness. (Can’t use display names for uniqueness.) I don’t think we care if they’re handed out sequentially, in discontinuous blocks sequentially, via Fibinacci series, randomly with an in-use check, or something else. Some of those implementations make more sense than others. :slight_smile:

Forum posts are linked from the requirements and the spec is derived from the requirements, though possibly I missed some links along the way. Does that meet the need?

2 Likes
11

Good point. I changed “user number” to “user ID” in the functional spec to keep options open.

2 Likes
12

No, not what I meant - sorry. Perhaps “a user chooses a flag reason from a list and (optionally) types custom text” makes my intention clearer. Not all flags require elaboration, except possibly an “Other” flag reason. What I mean is to make it clear that choosing one item from the list is always required. Minor nitpick, looking at it now :smile:

It does, I missed it previously.

Thank you for the clarifications ^^

13

Sequential ID internally. If you want to also create a GUID for each User and use that for the default UserXXXX name, that’s fine. But unless someone has a really good reason not to do so, let the DB automatically assign sequential IDs pretty much everywhere. I learned that lesson long ago, ignored it in one particular case on the advice of others, got burned by it later and added it (with the agreement of those same others, and with my email documentation of the original discussion where I lost out…) and have stuck to that rule pretty consistently since then.

3 Likes
14

Oh, optional text to augment a canned flag – yes, that would be helpful. There have been times on SE when I needed to use an “other” flag to point out non-obvious spam, which meant not using a red flag and thus maybe getting it taken down sooner. I’ll edit.

2 Likes
15

The spec now says “ID” rather than “number”, and the people implementing it can decide what form “ID” takes.

1 Like
16

That’s excellent.

@manassehkatz, I’d be interested in knowing more details about that bad experience you’ve had. Please ping me on Discord whenever you are able - I’ll be there in about 30mins from now (until late into the night, probably).

1 Like
17

I see nothing in your FS that isn’t in SE’s implementation – with due allowance for slight difference in terminology, e.g. if your “Feedback” is SE’s “Comments”.

Assuming we all know SE. your SE might be shorter and easier to understand if it said simply, “clone SE”.

As it’s meant as the FS of an “MVP”, then it could be “clone a subset of SE”.

A compact way to show that might be with SE screenshots, with the canonical “free-hand red circles” showing what existing features are included, alternatively “free-hand red scribbles” to show which features are omitted from the initial design/sprint.

As a front-end developer, do I have enough information to proceed to a design (for the parts that are specified)?

  • If you’re cloning the SE design just say so.
  • If you’re different from the SE design then it what ways?
  • Or are you trying to do cleanroom design as if you had never seen SE?

As a front-end developer (which I guess I am i.e. I actually already developed this) I guess I need to define the following as my “external interface” details before I can start coding:

  • UI design:
    • Either pixel-perfect design (screenshots like I might get from a UI designer using Photoshop or Zeplin)
    • Or some other specification of what data is displayed
  • API design (e.g. a REST API)
    • What URLs (i.e. routes) exist
    • What data is returned by the server from each URL?
  • Runtime environment – in what programming language is this coded, using what library or framework, and is this code run on the server and/or in the browser (and why)
  • Who (which person or people) do I interface with to agree on e.g.
    • API with the backend (and/or defining the routes or URLs of a REST-like API)
    • Data on the page
    • Layout (e.g. using CSS) of data on the page
    • Behaviour of page elements (e.g. the “tag editor” to select a tag or create a new one is one of the more complicated)

As a database designer, do I have enough information to proceed on a schema (ditto)?

I think somebody must create a data dictionary from your wordy spec.

And that data dictionary doesn’t only affect the database – it also defines what data is passed through the API (between the front and back ends) – and displayed in the UI – and created in the UI.

As a back-end developer, do I see anything that raises alarms

SE’s design uses paging – e.g. a configurable number of topic per “page” (not “all topics on one page”) – presumably your design will be similar or identical.

The “alarm” IMO is just the quantity of data (e.g. SO has 18 million topics), and the total number of users, and the number of views/additions per day.

You might or might not be interested too in other non-functional requirements (“performance” is just one and a crude one).

18

Codidact is obviously inspired and motivated by SE, but it’s not meant to be a clone. One of the risks of reducing things to “like SE” instead of actually specifying what we want is that we’ll inadvertently carry along SE baggage that we don’t want. Some differences we’ve already identified:

  • Scoring/ranking of answers will be different.
  • We are discussing optional public votes as a mechanism for experts to weigh in easily.
  • We either won’t have or will not prioritize a reputation score.
  • Privileges will be earned based on (specific) activity, not just on reaching a certain rep level (even if we have rep).
  • Our approach to comments/discussions/feedback will be different. There will not be a separate chat system, at least for discussions on particular posts; whatever we do will be integrated.
  • We haven’t specified question closure yet and it might be different. We probably will not “bake in” global close reasons but instead allow communities to decide what they want.
  • We haven’t discussed whether we’ll even have badges, let alone for what.
  • We probably won’t have bounties because without rep how would you fuel them?
  • We will allow a lot more per-site customization than is available on SE.

Thanks for the specific feedback; that helps. To respond to a few things you raised:

I’ve been assuming there’ll be a UI design that fleshes out the functional requirements into a design proposal, and then after review that’ll be refined into something detailed enough to implement from (pixel-perfect or detailed wireframes or whatever the developers need; I’m not a UI person so I don’t know).

We’ll definitely need an API, which is completely unspecified right now.

On the data dictionary, some of the back-end/DB folks are working on devising a schema design, so that’s coming. It’s pretty central; we need it early.

Paging: good catch; yes we want that.

Thanks again.

4 Likes
19

In summary:

  • Voting and privileges will be “different”
  • No reputation nor badges
  • No separate chat, and comments will be “different”

These details seem to me to be add-ons or frills compared to the basic functionality.

IMO the “basic functionality” is support for the following types of data/item …

  • Users (name, gravatar)
  • Topics (each with a title, text, author, tags, date, and answers)
  • Answers (each with a topic, author, date)
  • Tags (title, short description, long description, associated topics)

… where “support for” means implementing the software which lets you do just the following CRUD-like operations, for each of the types of data listed above:

  • List all (show a list of item summaries with sorting, filtering, and paging)
  • View one item in detail (e.g. selected from a list)
  • Create a new item, and edit an existing item
  • Navigation between the different types of item (hyperlinks within the page, and in the page margins and/or in the navigation bar at the top of the page)

Perhaps implementing that can be a first sprint. It would require you to define and implement:

  • The front-end and the the back-end
  • The API between and/or within the two (including URLs and data formats)
  • The run-time environment of each
  • Code to which additional features can be added (see Gall’s law)

Well it’s open-source, right? So …

But “planning to customise” seems wrong to me at a very early stage – it’s saying, “I can’t specify even one design, so please write the software so that it’s configurable so that other people can implement anything.”

As a software developer I have to implement something in particular, without a specification then I can’t start – or I can start, but only by starting without you.

Instead of their being no specification, what I would want (as a coder) is either one design specification (“please implement this design spec”) – or two specifications (“write the software such that it can satisfies either or both these specified designs”).

That’s why I cloned the SO UI when I implemented the “basic functionality” defined above – because I needed a/any design specification in order to write code (i.e. to implement something in particular) – I can implement i.e. code a front end or a back end but “I’m not a UI person” i.e. a designer, so.

There are several APIs, at different layers/levels of the system. One of them is simply the set of URLs between the front end and the back-end – e.g. …

  • /questions?tab=active&page=2 – to get some of the latest topics
  • /questions/[id]/[title] – the URL or “route” to get a specific topic

… which is the interface between the front and back ends (assuming a REST-like API).

Then you need to specify the format of the data.

That sounds old-school – I guess that “schema” is a consequence of using the MS .NET stack and SQL.

When I did my prototype I defined the data using TypeScript – i.e. a set of TypeScript interfaces to define the types and the data members of each type – https://github.com/cwellsx/react-forum/tree/master/src/data

That might looks trivial but it’s what/all a front-end needs – the front-end might be entirely uninterested in any database-specific implementation/schema.

20

By the same reasoning, Quora and Yahoo Answers are just SE clones with minor differences. I prefer to instead specify what we are (and, by omission, aren’t) building, instead of leaving developers to guess.

I also want to see us start building. We know enough to proceed; we’ll fill in more as we go. The goal of the functional spec (note: not a technical design spec, a functional spec) is to make sure we agree on these foundational points. We do, as far as I can see.

I meant within an instance. Anybody can take the code, make changes, and stand up a new instance. That’s not what I’m talking about. An instance will (or can) host many communities, and we will allow those communities to customize aspects of Codidact’s behavior. SE does this too, with things like custom close reasons, custom post notices, custom professional-services disclaimers, changes to certain parameters like how many answers cause comments to auto-collapse, and more.

The functional spec describes the desired outcome. We then need a deeper technical design that specifies how we’re going to implement it. There are front-end and back-end dev teams and I’m sure either would welcome your participation as they do that design and start implementing.

3 Likes