How do I describe my database schema?

This is a post in which I explore what would be the best way to explain my current database schema for DenseLayers (my current project) in a clear and concise manner – which I will do in another post. This means that this is a rambling post about how I should write that future post. Writing great documentation (whether for yourself or others) is a skill and it should be practiced thoughtfully. I want to compare different ways of organizing/structuring the ideas on paper so that they make the most sense.

Update: I realize other readers may not know what DenseLayers is because I haven’t introduced it yet. It’s a website where people can discuss research papers online, paragraph-by-paragraph. I believe that having to read a paper alone by yourself is a terrible waste of time. Reading research should be collaborative.

I guess the best way is to start with the goal in mind – by the end of reading that future post, I want the following from the readers:

1. I want them to know what high-level decisions I’ve made about the website and its functionality.
2. I want them to see how I translated those decisions into a database architecture.
3. I want them to see what decisions I’ve made regarding privacy and anonymity, and how they too translate into the database schema.

Yeah I think that makes sense. Let’s try a few different ways to organize explain these ideas in a cohesive manner.

Okay, firstly readers need to know that what I’m doing right now is just the first version of the website, which is an MVP and not meant to be perfect. So most of the features that I envision in the future will not be there. Cool. Decision: I shall write a couple lines in the beginning about how this is just the first version.

Then, I should describe the features of V1, including the reasons for why. So maybe describe them as…

1. Front page – what it will contain
2. Paper page – what the paper page will look like, what features it will have?
3. User sign up and login, password reset etc
4. User profile and settings
5. A form that I can use to quickly add new papers to the website – should only have admin access. How would this form work?
6. How does user data etc get displayed on the paper page? (It not very simple)
7. Language flexibility – people should be able to use the site in any language they want
8. What kind of analytics and user activity I will collect from the site.
9. Should there be a spam filter already? (Another decision to make!)

Which basically seems like describing the wireframe I drew over a year ago. Maybe I should include screens from the wireframe.

I think if I split the website functionality like this, it makes sense. Not too deep nor too shallow. So, I can now show readers my database schema and teach them about it?

Also it would obviously be worth mentioning that I’m using a SQL database – maybe that should be the first thing? I guess the readers who read that future post will be those who have a technical background and are interested in learning about my database schema.

No wait – I can’t just assume maybe I should create a short list of personas of readers, split by technical ability, and use that to drive the decision?

1. People who don’t know anything about database schemas. These people likely are just into the website that I’m actually building, and happen to find the blog post codex?
2. People who know about database schemas, and find that codex entry many months/years later when they’re curious about how it was built. <– I guess for these people, the decisions that govern the schema design are more interesting than the schema itself. But I guess we’ve already taken care of that in the proposed structure above. So we’re good here.
3. People who are very actively involved in the building of this website and want to have a clear picture of why anything is done. Wait, is that just me? In any case, this section of the readership is actually most important – because the most frequent reader of this codex will be myself. Decision: anything that Present Me writes should be useful to Future Me.

Future Me, you better be grateful to me for making decisions in your best interests.

Anyway – It seems that #1 is not a useful section of the audience to structure my post about. I’d rather focus on #2 and #3, and… wow, that brings us back to ground zero. Looks like I learned nothing from this whole “audience persona” mental exercise. So from this exercise of creating audience personas, the only thing I’ve learned is that everything I write should be useful to my future self if he ever needs to go back in time and look at his my decision making process.

Letting that aside, I don’t know the big advantages of SQL vs noSQL, do I need to talk about that? I pretty much went with SQL because it works perfectly for what I’m trying to do. That reminds me, I should read more blogs and watch some videos about noSQL because I barely know anything about it. Awesome, cheers!

Wait, what would be a good way to sign off at the end? Now this is one place where I should probably use something that is appropriate to a larger audience and not just Future Me. How about a few contenders:

1. Awesome, cheers! <– sounds weird-ish
2. Thanks for reading! <– too formal?
3. Cheerio! <– this one is pleasant, I’ve used it in emails a lot
4. That’s all, folks! <– can’t believe my brain farted this one. Cringe
5. See y’all later! <– same as #4
6. …nothing? Just end at the last logical sentence? <– sounds very flexible actually

So it’s a tie between #3 and #6. Let’s just go with #6 for now. After all I can always suddenly change to whatever I feel like. Wow, I just spent another 10 minutes overthinking something so trivial.