Expand repo scope for cross-component architecture docs

instructlab / schema

JSON schema for Taxonomy YAML

Apache License 2.0

0 stars 7 forks source link

Expand repo scope for cross-component architecture docs #5

Closed russellb closed 3 months ago

russellb commented 3 months ago

I feel we need a home for architecture and design documentation for issues that span multiple components. The schema is one example of a detail that needs to be coordinated across components, but there are others, particularly with backend automation, and automation with GitHub to assist in taxonomy development, triage, and review.

A follow-up to this change should be to rename the repo to a more generic name that reflects an expanded scope of artifacts.

Part of issue #4

Signed-off-by: Russell Bryant rbryant@redhat.com

xukai92 commented 3 months ago

+1 for this. so far we have design docs across different repos

https://github.com/instruct-lab/cli/blob/main/docs/workflow.png (source code in the same folder)
https://github.com/instruct-lab/taxonomy/blob/main/docs/review-process.png (source code in the same folder)
https://github.com/instruct-lab/taxonomy/blob/main/docs/backend.png (source code in the same folder)
https://github.com/instruct-lab/orchestrator/blob/main/flowchart.drawio.png (source code in the same folder)
https://github.com/instruct-lab/evaluation/blob/main/docs/eval-pub-flow.md it would be nice to consolidate them

russellb commented 3 months ago

Based on some discussion in #4, I created a new repo for this instead.

https://github.com/instruct-lab/enhancements

xukai92 commented 3 months ago

besides, what diagram format would you recommend? I like Ditaa (e.g. this) which is what I used for the CLI and Taxonomy plots, but I feel it's not very accessible for others to edit (or at least need some learning curve). The good side of Ditaa is that this is very flexible as you can draw in whatever the way you like, unlike Mermaid which sometimes gives me headache on it's automated layout (but I used it for the evaluation repo because it's much easier for others to edit).

russellb commented 3 months ago

I've used mermaid but find it difficult.

My current preference is https://excalidraw.com/. It's very easy to use. When you export the diagram as a PNG, you have the option to include json metadata embedded in the image so that anyone can load the image back into excalidraw to edit it.

xukai92 commented 3 months ago

cool. let's give that a try