Let's come up with initial structure of the documentation, based on data we have available See #1
Something along the lines:
Architecture/ - Pipeline - Metadata - Standart Test Interface How-To/ - Testing Quick Start - Pull Requests Detailed Guides/ - Standard Test Roles - CI Messages
'Architecture' - should it be a specific page or just a folder?
Metadata Update from @psss: - Issue assigned to psss
I propose to align the structure with what we currently have on the main CI portal:
I've drafted the initial version in fcd7fd3.
I'm unsure about the categories. If I have a problem or want to get started, where do I look?
If I have a problem or want to get started, where do I look?
Into Guides?
* Guides ** xref:quick-start-guide.adoc[Quick Start Guide] ** xref:pull-requests.adoc[Pull Requests] ** xref:faq.adoc[FAQ]
This seems to be quite natural place, I'd say.
I'd say FAQ should be on the top level to be discovered
then we need to have How-Tos rather than Guides, things which explain how to run a task.
Guides are interesting from the point of you of getting a full picture and a full lifecycle. But we need a place where we can collect tips and manuals with smaller scope
Then Tools and specification pages like (STI) are part of the CI Developer documentation, it shouldn't be on a top level.
Agreed with the FAQ on the top level. Regarding the level of detail I propose to use just two sections: Section aimed for newcomers with quick-start-like content and section with detaild information about the CI architecture. See pull request #23 for the whole idea.
After today's discussion the pull request has been merged.
Metadata Update from @psss: - Issue status updated to: Closed (was: Open)
Login to comment on this ticket.