I need this decision for different specs, for example:

• Legacy software deposit
• Sparse / Metadata deposit (now in docs)
• Metadata workflow- How do we dill with software metadata (T1344)

In T1683#31054, @moranegg wrote:

I need this decision for different specs, for example:

• Legacy software deposit
• Sparse / Metadata deposit (now in docs)
• Metadata workflow- How do we dill with software metadata (T1344)

I'm not clear on why this decision is blocking for you. If it's so urgent, use whatever is easier for you, will move it somewhere else later as we have done in the past :-)

That said, I think the best place for any kind of long-term document is docs.s.o, which means a rst document in some of the current software components or swh-docs as a fallback.
While working collaboratively in the early days of a spec, though, having it on the wiki (or even a pad, really) would be easier, because the barrier for contribution is lower. Which is what has happened for most of the specs you mention: born and developed on the wiki first, moved to docs.s.o later.

If this answers your main question in this task, feel free to close it. If not, please clarify what's still missing to clarify the proposed approach.

@zack Thanks for the answer.
It's not a blocker per se but I prefer to have a long term decision before moving the specs from different spaces, so for me it's a high priority.
It wasn't clear to me that it should be in the docs and that this is the long term decision.

The problem with having it in the docs, is that specs of higher level (like metadata workflow) must be in a specific repository, or can I have a specs folder in swh-environment?

In T1683#31093, @moranegg wrote:

The problem with having it in the docs, is that specs of higher level (like metadata workflow) must be in a specific repository, or can I have a specs folder in swh-environment?

That was my point about "swh-docs as a fallback". If it doesn't fit a specific repo, they can go in swh-docs, where we already have some cross-cutting material.

In T1683#31104, @zack wrote:

That was my point about "swh-docs as a fallback".

Good point, didn't understand that, my bad.
Maybe all specs should be in swh-docs even if there is a specific repo?
and have a link to and from the specs to the implementation?
This way we don't mix between functionality and implementation..

I don't think it's a good idea to move specs from the specific components they specify to a different repository (swh-docs), because that will just increase the chances (which are already quite high) that they will get out of sync.

This is resolved with the following decision as I understand it:
specifications of a component should be in swh-<component>/docs/specs/.
specifications of a a transversal functionality should be in swh-docs/specs/.