docs: structure

[Kjili]

Based on #401.

-- Background and Index/README -- what is it (example text exists) what is it for (example text exists) features what is it not who are we how to contribute license information Accessibility scope, goal vision? connectivity

-- related projects -- RECAST background information (what is it, what is it for, etc), check for existing documentation with @lukasheinrich

-- Getting Started --

authorization forms API

-- Specific HowTo/Examples -- [Use cases: task-oriented walk-throughs, GUI and API] see an example analysis record and how it can be used I am an experimentalalist, how can I use it? I am a theorist, how can I use it? What information do I need to prepare from my analysis? When should I do it in my analysis (whenever there is an update that you need to save; we version) I am continuing my colleagues analysis. How can I reuse the info [clone the record, start editing] How to use our API with a list of our resources (links/urls they can do requests), descriptions, etc: something like https://developers.facebook.com/docs/graph-api/using-graph-api and also https://about.gitlab.com/handbook/marketing/blog/ probably separate/highlighted hierarchy level: Guidance on how to publish via shell/API. This needs more thinking and these instructions shall/will be used as specs for the development part also. As a database provider within LHC collab, how can I contribute to or profit from CAP

-- FAQ (but also addressed before) -- [an user-oriented FAQ that contains the TL;DR version of documentation entries, which acts as a navigation interface of the documentation] Why do I have to enter information into internal databases AND here? - you dont have to; explain Do I have to use this rather long form or what other options do I have? - shell, API I can edit, can my collaborators edit my analysis too? - All your collaboration colleagues can read it, only those you invite specifically (personally or e-group) can edit as well Can I export the information for reviews/approvals? - yes address known concerns

-- Community -- explain the community concept, where help is needed try to convey the balance of importance when adding/removing details while offering support and guidance on how to get it

-- Support -- how to communicate with the user: chat support? Service now? Email? collaboration-internal contact persons?

-- Glossary/Reference -- ontology explanation status report, make clear what's there, what is not and what is planned and keep this maintained (also include what is possible) terminologies metadata schema

[xchen101]

tidied up Table of Content

[xchen101]

What it is

• [x] Scope and goal
• [x] Motivation
• [ ] Team
• [ ] Contributors
• [ ] Partners
• [ ] Related projects

Walk-throughs

• [ ] Submit an analysis (webform)
• [ ] Search for analyses
• [ ] Reuse an analysis
• [ ] Submit an analysis (API)

What it does

Capture

• [x] Data model and metadata schema
• [ ] Submission forms
• [ ] REST API
• [x] Connectivity
• [ ] Versioning

Search and retrieve

• [x] Search capability
• [ ] Facets/ filter

Review and compare

• [x] Authorisation/ access control
• [ ] Report compilation

Reproduce and reuse

• [ ] Analysis environment preservation
• [ ] Analysis take-over
• [ ] RECAST

Re-interpret

FAQ

Community support

• [ ] Feedback form?
• [ ] Contact information

Glossary/ terminologies

• [ ] Physics objects
• [ ] Storage systems
• [ ] Technologies/ software solutions

References

• [ ] Metadata schema
• [ ] Publications
• [ ] Presentations
• [ ] Development status/ timeline

Contribute to the project

• [ ] Github link
• [ ] Technical documentation

License information

• [ ] License
• [ ] Terms of use

[suenjedt]

A few questions and comments:

• what do you mean by "connectivity"
• I am surprised that "authentication and access control" is relatively late/down in the TOC. That is of general relevance and should come pretty high up.
• not sure about feedback form. possibly something more interactive would be good?
• unter what it is I would like to focus on purpose and functionalities (see for example the 2 page briefing that we had "why do we need CAP". Who has been contributing to CAP development etc I would detangle from this and move to an "about" page.
• I think the REAST part should be moved to the reuse/reproduce part.
• the walk-throughs (nice idea!) I would also put higher up in the TOC

[suenjedt]

And I would focus on the exp side of the user and leave TH out for now. Too early stage, I think

[xchen101]

@suenjedt

• connectivity shows the external databases/platforms that are or will be connected to CAP for various reasons, e.g. collaboration internal databases for auto-complete, HEPData for data publishing etc.
• thanks for pointing out, I will emphasize the "closeness" of the platform in the general introduction. The "review/compare" section mainly elaborate on how different levels of authorization helps with the approval process.
• maybe gitter?
• I imagined "what it is" to be the "about" page, sort of like on HEPData here, and provide a little bit consistency across HEP platforms.
• RECAST kind of give me the reinterpretation vibe. but sure, if you think that's more appropriate.
• they can be moved in front of the "What it does" part (for the record, these are not the real names of the sections, just placeholders) I was thinking walk-throughs can be linked to a more prominent place on the page, again see top right corner of HEPData so users can access them directly. that being said, I think the section order of this file is not the most important thing. the more sensible way of doing it is probably placing the right "help" button next to the relevant scenario, thus people will more likely jump right into the sections they need, instead of going to the documentation site and sift through the TOC. obviously this will not be ready for the workshop, so yeah I will still change the order.

[suenjedt]

Closing as we should be revising the content (with @xchen101 and @sefeg). Possibly revisiting this, but the "to do's" depend on a revised structure. Hence, closing this TOC.