Notes:

• I wonder if it would not make more sense to put spec-meta-deposit.rst and spec-sparse-deposit.rst within blueprint.rst since these are other "use cases"
• I don't really get the point of the specs/spec-technical.rst file - it should be deleted (maybe keep one or 2 paragraphs in there)
• I think dev-info.rst and sys-info.rst should be moved in a subsection ("Reference" or "Technical Doc" or something)
• I think the tests/tests_HAL.rst file should not be in the docs

I also think that if we use the "blueprint" terminology, then the blueprint section should list all the specifications, implemented or not, but make it very clear what's done, in-progress or only planned.

I wonder if it would not make more sense to put spec-meta-deposit.rst and spec-sparse-deposit.rst within blueprint.rst since these are other "use cases"

Personally, I like the documentation files separation. I kinda don't want to have to deal with only one file to edit and scroll like a mad man when i want to edit something.

I'm fine with rendering the documentation as one page though and do as you propose (which i think is possible (?) without having to merge all files into 1).

I don't really get the point of the specs/spec-technical.rst file - it should be deleted (maybe keep one or 2 paragraphs in there)

I think it was meant to be a little more technically detailed than the main specification (which tried to keep function about the functional need).
I agree with keeping some paragraphs, notably the statuses diagram which you already exposed somewhere else (in the main spec iirc).
So i guess, it could go away.

I think dev-info.rst and sys-info.rst should be moved in a subsection ("Reference" or "Technical Doc" or something)

sure.

for the record, dev-info.rst was to ease starting up development on the deposit.
At the time i started up writing the deposit, i struggled a bit to understand how all the django stuff came together.
And once i got a better grasp of it all, I added that part so it could help others.

The same goes for the sys-adm.rst part but this time for the operational part of the deposit (how to trigger the db migrations scripts, and all that).

I think the tests/tests_HAL.rst file should not be in the docs

Ok, but where does it move to then?
If it's there, it's been useful or necessary to someone, i'd say @moranegg here.

That's part of another struggle we have here, we don't always know where to put the documentations.
So it ended up where it made most sense, in the deposit repository. ¯\_(ツ)_/¯

I also think that if we use the "blueprint" terminology, then the blueprint section should list all the specifications, implemented or not, but make it very clear what's done, in-progress or only planned.

sure

That means currently, from the top of my head:

• sparse-deposit (not implemented)
• metadata deposit (in-progress)
• ...

In T2751#52342, @douardda wrote:

• I wonder if it would not make more sense to put spec-meta-deposit.rst and spec-sparse-deposit.rst within blueprint.rst since these are other "use cases"
• I don't really get the point of the specs/spec-technical.rst file - it should be deleted (maybe keep one or 2 paragraphs in there)

Agreed

• I think dev-info.rst and sys-info.rst should be moved in a subsection ("Reference" or "Technical Doc" or something)
• I think the tests/tests_HAL.rst file should not be in the docs

No opinion

In T2751#52343, @douardda wrote:

I also think that if we use the "blueprint" terminology, then the blueprint section should list all the specifications, implemented or not, but make it very clear what's done, in-progress or only planned.

With @ardumont we suggest to add to the section title or subtitle the status of the blueprint section.
Maybe following also the https://www.repostatus.org/ vocabulary.

We can use [Concept] for not implemented yet and [Active] and [WIP] for specs that are currently developed.

In T2751#52450, @ardumont wrote:

I wonder if it would not make more sense to put spec-meta-deposit.rst and spec-sparse-deposit.rst within blueprint.rst since these are other "use cases"

Personally, I like the documentation files separation. I kinda don't want to have to deal with only one file to edit and scroll like a mad man when i want to edit something.

I'm fine with rendering the documentation as one page though and do as you propose (which i think is possible (?) without having to merge all files into 1).

I also like working only on one file at a time, but agree to have one page on the web doc.

I don't really get the point of the specs/spec-technical.rst file - it should be deleted (maybe keep one or 2 paragraphs in there)

I think it was meant to be a little more technically detailed than the main specification (which tried to keep function about the functional need).
I agree with keeping some paragraphs, notably the statuses diagram which you already exposed somewhere else (in the main spec iirc).
So i guess, it could go away.

I don't mind, but we should think of an overall strategy on how to organize docs directory (for all repos, not just deposit).
I push for a strategy to keep the functionality of the doc file with the same name in all documentation.

1. usage
2. development
3. deployment