Define a directory structure for the docs

[ifraixedes]

Motivation/Why?

• We have one design doc merged under a directory.
• We are going to merge a new one (Dlm/version config #2) under another directory.
• Both design docs are related to satellite, however:
  • The one to merge isn't currently in the satellite directory as the first one.
  • The one to merge is also related to Edge services for supporting more S3 endpoints.

What needs to be done?

• Determine a directory structure or keep the documents in the root of the repository.

Acceptance Criteria

• In the case that we decide to have a directory structure:
  • Define if there is one level or sub-levels.
  • Define how the directory structure is created, for example per system, area, etc. The structure should be clear so future design doc writers know where to add their document (in an existing directory or creating one following the defined structure)
• Decide where the old design docs should be kept. Unblock Move old blueprints to this repository #4
• Document in the README about the directory structure, or in the case of keeping the documents in the root, explicitly mention it.

[ifraixedes]

I'm running out of ideas at this moment, on how we can classify the documents, considering that if we use a directory per "service", some documents may fall into more than one, so my current proposal is to keep them in the root of the directory and in the future if we realize that we need some structure, find one looking a the documents that we will have at that moment to find out how to classify them.

Regarding the old documents, I'd rather create a folder named "old-blueprints" or something like that.

[jenlij]

Perhaps if it's clear which sub-directory it belongs in, we move it there. Otherwise, like you said, we can leave it in the root. We could even have people add labels to the doc if that helps. eg satellite, edge, s3

[egonelbre]

An alternate approach is to ditch the folders and start each with a creation date (or a sequence number) and then add tags to frontmatter.

e.g. 0001-admin-back-office.md or 20230816-admin-back-office.md

tags: ["satellite", "satellite/admin", "support"]
---

# Admin Back Office

[ifraixedes]

I like the idea of using tags in the frontmatter and using a creation date.
Sequence numbers would also work, but it's more difficult for the creator to find the following one because there may be several documents in progress. Clashes should be fine because we'll have them with the creation date too, but the creating date doesn't require the owner to look around to find out which number to use.

@jenlij @egonelbre if we go with them please 👍 this comment, otherwise post your concerns or also post if you think that more people should be involved in this conversation. If I have your 👍, then I will go ahead to update the one that I created and post a comment in #2

[egonelbre]

Sequence numbers would also work, but it's more difficult for the creator to find the following one because there may be several documents in progress.

We don't have that many concurrent documents either, so I don't think it'll be a large problem. And even if we commit two with the same number, it's a simple filename change.

[egonelbre]

If I have your 👍, then I will go ahead to update the one that I created and post a comment in #2

We can merge that regardless, because we'll need another PR to fix the naming of the other document anyways.

[ifraixedes]

We don't have that many concurrent documents either, so I don't think it'll be a large problem. And even if we commit two with the same number, it's a simple filename change.

Using the creation date is simpler for the owner, anyway, I'm also fine with using a sequence number, it's about my preference for the former.

We can merge that regardless, because we'll need another PR to fix the naming of the other document anyways.

Yes, no problem, I didn't think of blocking it because of this, but if these changes go first, I can drop a comment on that PR so they can be sorted before the merge.

[ifraixedes]

Do we go ahead with the tags and sequence number then?

[egonelbre]

Honestly, I don't have a strong preference between sequence and date.

[ifraixedes]

Can I use my strong preference:sweat_smile:? otherwise, we can flip a coin

[egonelbre]

@ifraixedes sure.

[ifraixedes]

OK, I will create a PR to make this happen