Documentation structure (ADR?)

[noandrea]

Collecting the feedback from the Design session, the following could be a starting point for the documentation

/README.md
	section: intro
	section: lightpaper
	link: /docs/modules.md
	link: /docs/architecture/README.md
	section: quickstart

/docs/modules.md
	link: /x/did/README.md
	link: ....
	
/x/did/README.md
	section: summary
	link: /x/did/docs/references.md
        link: /x/did/docs/howtos.md
        link: /x/did/docs/tutorials.md
        link: /x/did/docs/explanations.md

/x/did/docs/assets/

where

• section indicates a content block within a markdown file
• link indicates a link to another markdown file in the structure
• /x/did/docs/assets/ contains svg or other stuff for documentation

[noandrea]

@SenorMonito I'm not sure how to proceed with this one, if to discuss it first, make an ADR or directly make a PR.

At the moment I'm using the strucutre above to document the did/identifier module

[noandrea]

for the module doc structure, cfr https://documentation.divio.com/

[minkyraccoon]

@noandrea - the https://documentation.divio.com/ looks like a very nice way to do this and is providing the inspiration.

I'll raise an ADR for this as suggested, but I was going to propose this functional structure, which could represent the Sphinx-like representation with the relevant files underneath.

Introduction
    README.md

Tutorials
    docs/tutorials/get-started.md
    ...

How-To
     docs/how-to/quickstart.md
     ...

Reference
    docs/reference/glossary.md
    docs/reference/modules.md
            link: x/did/README.md
            link: x/vc/README.md

Explanation
    docs/explanation/README.md
    docs/explanation/articles
    docs/explanation/articles/CosmosCashRegs
    docs/explanation/articles/CosmosCashRegs/article.md
    docs/explanation/ADR
    docs/explanation/actors
    docs/explanation/actors/issuers.md
    docs/explanation/concepts
    docs/explanation/architecture

[minkyraccoon]

With regard to the structure

/x/did/README.md
	section: summary
	link: /x/did/docs/references.md
        link: /x/did/docs/howtos.md
        link: /x/did/docs/tutorials.md
        link: /x/did/docs/explanations.md

I think a top-down approach for the individual files might be better for navigation.

docs/reference/did.md
docs/howtos/did.md
....

then the /x/did/README.md would have this structure:

section: summary
link: docs/references/did.md
link: docs/howtos/did.md
link: docs/tutorials/did.md
link: docs/explanations/architecture/did.md

[noandrea]

the rationale behind the originally proposed structure is that the module documentation stays within the module folder while the project documentation stays at repo level.
The advantage of the approach is that if you want to "move" the module somewhere else you don't have to cherry pick the documentation and update all the references, but you can just extract the module folder. But I don't know if this is ever going to be an issue.