Write more developer documentation (onboarding video, comments, architecture diagram)

jbilcke-hf commented 4 months ago

Context

As there are now code bounties, new developers might join the project but be a bit lost due to the lack of documentation.

Goal

Today I'm pretty happy to help and answer questions in the Clapper Discord (https://discord.gg/AEruz9B92B) but it would be better to have documentation to make it scale.

So we need to work on:

[ ] onboarding video(s)
[ ] code documentation
[x] diagrams

Limitations / things to checks

T.B.D.

How to implement

[x] create a diagram with Excalidraw to show the interactions between the services and NPM modules
[ ] Write a series of videos to explain each aspect of the project to developers (how screenplays are converted, data structure, the webgl timeline, rendering, AI assistant.. etc)
[ ] Write a text document to explain a bit the architecture of the services
[ ] Make sure all functions and components are documented (TypeScript code comments)
[ ] Improve the README.md

Acceptance criteria

Documentation is sufficient enough for a newcomer to run the app / do changes

jbilcke-hf commented 4 months ago

I've added a first version of the diagram in /documentation/diagrams/:

architecture

lalalune commented 4 months ago

Since the project is strongly typed in typescript, we can add easily set up an automatic workflow of typed API documentation to Docusaurus, and it will generate on CI/CD.

For example I have this project: https://github.com/jointhealliance/bgent and every time I publish, the docs publish to https://bgent.org

If we add TSDoc comments to the major functions and whatnot, it will be proper searchable API documentation unified between the codebase and the docsite.

If that sounds cool I can work on it.

I think we're in an age where-- tbh I just copy and pasted the whole codebase into Claude and talked to it-- but having "proper" documentation and all that engenders a certain kind of trust from people in the project's quality. Like good TS typing, or the silly Github badges and whatnot. And the best thing for this project would be to attract a couple more dedicated contributors.

jbilcke-hf commented 4 months ago

Yes you're 100% right @lalalune , better document should help Claude figuring things out (especially meta documentation, explaining the purpose of things at a higher level than just the code, like why, interactions with other components)

I'll try to be attentive to this starting from now on

sendn0des commented 4 months ago

Happy to help on the onboarding videos when we're ready.

jbilcke-hf / clapper