Functional spec begun: please review

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

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

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

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

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

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

2 Likes

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 ^^

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

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

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

1 Like

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

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).

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

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.

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

I suppose it was ever thus – yes.

The big difference seems to me the ethos – i.e., “This site is all about getting answers . It’s not a discussion forum. There’s no chit-chat.” – and the moderation (whether and how posts are moderated), and the community (what the questions and answers are).

Well done then, I guess.

I think a “system” is specified by its I/O – what input it accepts and what output it produces – and in the case of a web app that specification is more-or-less defined by its UI (plus some “non-functional specifications”).

As a coder I’d hope to work off one or more UI design specifications – those would be my input, those would be my marching orders (plus whatever internal or external APIs or other developers I must interface with).

And as a sole developer, or a project manager for a non-technical boss, I’d either agree on a simple UI – like a wireframe or sketch plus some vanilla styling like Bootstrap – and/or have a UI designer to customize the pixels.

That’s the “UI design”. From that a developer can infer what all the data are.

Something like this, even, is a spec of a sort that a developer could run with (i.e. implement) – I don’t know whether that spec is “accepted”, though – the only answers there are people complaining about the choice of font and colour (which are trivial to change since they’re controlled by CSS).

And I guess someone might want to specify several designs and say the software must support any-and-all of them – to whatever extent the software is designed to support being “customised”.

The “technical” aspect of design – the implementation architecture – is all just about invisible to end-users, therefore nothing that a non-technical boss might have an opinion about or know. Developers might often select a technology stack based on whatever they know already, or based on whatever new shiny they want a chance to experiment with – and people might get into religious issues – like, “Which is important: ‘ACID’ or ‘web-scale’?” – which might be tedious to resolve, or resolved wrongly, unless you can Lock 'em Up Together. Apparently there is an architecture selected now – ASP.NET Core – I don’t know why though, I haven’t seen the definition or discussion and don’t know where to look for that.

Ha.

My instinct is principally to “finish” (define, implement, and deliver) a coding project – something of a killer instinct – I’m not so sure about “participate”.

How should one get in touch with either of those teams, or a project manager?

Are there (or will there be eventually) any “blessed” specifications somewhere for a coder like me to read and from which to dequeue some task to be completed?

Is it a matter of posting “Hi can I help with something?” on ‘Discord’ – then waiting, for somebody who’s willing to chat?

And hopefully your chef or chefs have it all in hand already, yes?

2 Likes

Mostly yes. You can also ping an @Admin and ask for a Contributor role. They grant you write-access to some dev-internal channels.

There isn’t one yet, at least according to my knowledge. I’m sure there will be one, once we start developing.

As I said, ping any @Admin or the @Team Lead or the @Tech Lead.

(pings are always meant to be in Discord)

1 Like

I’m thinking that a rapid iteration cycle, combined with requiring early feedback and requesting clarification often, will do the trick fine and allow us to launch an MVP much earlier than if we were to wait until a proper, detailed functional/technical spec was made. This of course would not be the case (most likely) if our project was properly funded and had a full-time professional requirement analysis team working along a professional full-time documentation team under a project manager’s supervision. But given our constraints, that’s just not happening so we go with the next best strategy.

1 Like

If by “iterate” you mean, “write code before you write a spec (e.g. a UI spec)” I guess I’d be inclined to do that if:

  • If the client is too non-technical to understand (read, edit, and approve) a paper specification – e.g. screen mockups with descriptive text (or e.g. pencil sketches and an audio conversation)
  • Or if the client wants their end-users to test (i.e. run) prototypes

Otherwise I’d want a spec before coding – so I’d write one with the client, and/or they might be give me some design and I’d ask questions about it.

The UI design might be sufficient for a web-app. It is “design”, and more detailed than (perhaps the next stage after) the “functional spec” – IMO it’s necessary and sufficient:

  • “Necessary” because you can’t code a UI without one, implicitly or explicitly
  • “Sufficient” because what defines a system is its I/O and the UI is the only interface visible to a user and/or a client – given a UI a developer can infer the rest of the implementation (e.g. data and behaviour, data-processing).
  • I think that UI design “desirable” too – something a client can talk about and understand and approve (i.e. want).

Apart from the UI design, if I’m the one developer of a new project, I might only want:

  • Team design – who else do I talk with?
  • Non-functional specifications – e.g. performance?
  • What other systems is this required to interop with (hosts, browsers, 3rd-party data sources and network services, email)?
  • Any IP issues – e.g. open-source, licensing?

That (“UI design first”) is assuming I’m doing it – and don’t want to waste my time developing something the client doesn’t want.

Doing the UI design is a bit of a test, too, or milestone. Because you might like to do “risk-first” development, i.e. schedule the riskiest things first, i.e plan development so as always to eliminate whatever the current biggest risk to the project is. And IMO “cannot find a client” and/or “cannot agree on a design with the client” are the biggest risk – the only risks which are outside the developer’s control – because implementing the design is well understood by developers, and maybe the only remaining implementation risks (after the external interfaces like UI are defined) are like, quality, budget, maintainability.

I didn’t mention “development team, development process, and software architecture design” above – though they might be necessary, that’s like an internal implementation detail which needn’t wait on a client’s approval.

I think I’d want a UI design though, maybe you have one but I haven’t seen it. If you’re in any hurry hurry then it could be a phased design, e.g.:

  • We definitely want this (specific design for essential features) so implement this design first
  • We haven’t decided on a further design for these other features yet, but we probably will later and they’ll be add-ons to the initial design, so you can ignore them for now and concentrate on the initial design first

Hopefully anyone involved in nailing down a UI design is savvy to what can be done with CSS – to foresee whether any given uncertainty in the UI design spec would require changing bones or skin – to tell whether or not it’s an uncertainty which it’s better to resolve now. There is, similarly, understanding whether the design for some new/advanced/uncertain feature will merely require an addition to an existing base design, or some more fundamental change. For example, “add the ability to vote on existing posts” might be merely an additional function, conversely “support real-time collaboration on a document” might be an example of some more fundamental change that would require rework of the software design.

21 posts were split to a new topic: How should (subject-)experts be recognized?