Flesh out scope of project

[monty5811]

What is the scope of this project?

Which aspects of http://reformed.tech/2016/07/developing-a-common-brain-for-our-systems/ should be included or left to other projects that build on top of this API?

Should we include RSS feeds, email notifications on new resources, for example? Or is that beyond the scope of the project and should be another system that talks to this one?

[sixstring]

Whatever web user-interface we create will certainly need to incorporate these types of features, but whether this specific project should include them should be a group discussion. At this point, I think it might be best to keep it all together. Even so, I think working on the core functionality first is key.

Storing and organizing the data is basic. I'd probably even put an API including an exposed Scriptural search function as a higher priority than a web interface since we could use the API on reformedforum.org. Searching resources by Scripture reference and easily linking to and including book metadata is huge for us.

[MarkDavidGoddard]

I agree that the baseline API is the most important thing to nail down. Lots of apps can be built on top of it. Has there been any work to define the API yet? We have had success using http://swagger.io/ to define and document our APIs at the office and I recommend it or something similar.

[kabucey]

I agree that we should take an iterative approach. Get the basics down and working well, and then start to add on other things.

[timblack1]

I noticed that https://github.com/reformedforum/reformed-nous/blob/master/reformed_nous/nous/models.py defines some model objects, but those objects don't define any way to handle scripture references, or any relations between objects, both of which are requirements mentioned at http://reformed.tech/2016/07/developing-a-common-brain-for-our-systems/. Since I read an overview of software development recently at http://mixmastamyk.bitbucket.org/pro_soft_dev/, this made me think some more work needs to be done defining the project's requirements and design.

Specifically, I think this project is at the requirements-gathering stage (see http://mixmastamyk.bitbucket.org/pro_soft_dev/sdlc_2_req.html). It would be wise to document the project's specific requirements in a Markdown document in this repository; the blog post at http://reformed.tech/2016/07/developing-a-common-brain-for-our-systems/ is at least a beginning of describing the project's central problem, goals, and requirements, but more specificity would be good.

After being certain about the requirements, then the project is at the design stage (see http://mixmastamyk.bitbucket.org/pro_soft_dev/sdlc_3_des.html). At this stage it would be wise to document the software's design's specifics, again in a version-controlled document, including the following:

1. Define the project goals.
2. Define the system architecture/infrastructure.
3. Define the database model.
4. Define the interfaces to other systems.
5. Define the background tasks.
6. Define the user dialogs and the control flow.
7. Define the non-functional requirements (response times, security, …)
8. Create a dictionary for all relevant concepts/entities.

Then you're prepared to move to the implementation stage.

Of course it's fine to do all of these at once, and cycle back from implementing a prototype to refining the requirements and design as you gain a clearer perspective.

In one recent project, the team I was on documented these things in a shared Google doc, which worked well except that it was not versioned with the code. So I'd recommend using Markdown docs in this repo.

[timblack1]

Oh, I see there are a couple relations present in models.py.

[timblack1]

Would it make sense to merge all the other Django app's models under the reformedforum Github group into this repo?

[monty5811]

I agree, we definitely need to plan things out a little. I think the current stage of this repo is a "conversation starter" to have something we can begin to talk and plan around. I suppose the best thing to do is focus on #11 to begin with?