Advice/tips for component documentation

Tom Ireland · 2024-10-24T17:30:55.443+00:00

Hey, community and 's. I'm looking for some advice/tips on component documentation. I'd like to auto-create (as much as can) documentation on components that I've created so that I can see what attributes each component expects, what attributes types are e.g. , , etc., and capture additional explanatory information.I've had a couple of ideas but not sure how to implement them yet and if it'd be a simple approach. - I saw you did this with Spark Pro. Do you have any pointers?

Tom Ireland
1 year ago
Hey, community and toddle-hero's. I'm looking for some advice/tips on component documentation. I'd like to auto-create (as much as can) documentation on components that I've created so that I can see what attributes each component expects, what attributes types are e.g. boolean, string, etc., and capture additional explanatory information.

I've had a couple of ideas but not sure how to implement them yet and if it'd be a simple approach. @Max - I saw you did this with Spark Pro. Do you have any pointers?
Lucas G
1 year ago
The toddle team has mentioned that they will implement enums at some point so that will help.
I don't know if tehre's any way to 'auto-create' docs
Lucas G
1 year ago
I think naming conventions help. For example, naming an attribute is-active where the prefix is means it is bool
Other than naming conventions, any documentation is pretty much up to us to do
DarrenBignall
1 year ago
Not sure how it is done, but @Victor Giron UI library has a copy button that copies the component as json, so it can be copied from his site and pasted straight into the editor, if you copy one and paste it as json somewhere you can access the attributes, the text values etc. Is that the sort of thing you are looking for?
so if you can store this somewhere and then use it to populate the attrabute, variables etc for each component
Lucas G
1 year ago
That doesn't tell us what the attribute/variable types expect
Which is the main thing to document in my opinion
DarrenBignall
1 year ago
Yes. You’re right
Victor Giron
1 year ago
I would love to know that haha for now I'm doing that manually
Victor Giron
1 year ago
To make it faster I turned the row into a component
Tom Ireland
1 year ago
Thanks for the input so far, folks!
@Victor Giron
To make it faster I turned the row into a component
Tom Ireland
1 year ago
I like this idea.
Max
1 year ago
Hi @Tom Ireland! We created a CMS to hold all the component information. That way, we can document in the backend and in the frontend it just works. On average, the documentation of a component takes about 5 minutes in our system. But it was tricky to set up 😅
@Max
Hi @Tom Ireland! We created a CMS to hold all the component information. That way, we can document in the backend and in the frontend it just works. On average, the documentation of a component takes about 5 minutes in our system. But it was tricky to set up 😅
Tom Ireland
1 year ago
Thanks, Max. Do you still have to manually update the documentation in the CMS or did you manage to figure out a way to automate it? Or do you mean when documenting in the backend, it just magically does all the stuff in the frontend?
@Tom Ireland
Thanks, Max. Do you still have to manually update the documentation in the CMS or did you manage to figure out a way to automate it? Or do you mean when documenting in the backend, it just magically does all the stuff in the frontend?
Max
1 year ago
We fist document our components and then build them. Makes more sense to us. So we do the documentation in our CMS (AI supported) an then they are included in our documentation system. But there is no direct connection between toddle and the docs
@Max
We fist document our components and then build them. Makes more sense to us. So we do the documentation in our CMS (AI supported) an then they are included in our documentation system. But there is no direct connection between toddle and the docs
Tom Ireland
1 year ago
Thanks for the insight, Max. Really appreciated. 🙂
💪1
Lee Russel
1 year ago
Do you guys take notes as you develop new functionality in a branch? Or just document the high level functionality of components / pages / variables inside of your documentation?

I would love to see some examples of the structures you use. I am just designing our documentation process now as we move beyond just doing POCs in toddle into more complex projects
@Lee Russel
Do you guys take notes as you develop new functionality in a branch? Or just document the high level functionality of components / pages / variables inside of your documentation?

I would love to see some examples of the structures you use. I am just designing our documentation process now as we move beyond just doing POCs in toddle into more complex projects
Tom Ireland
1 year ago
Personally, I add as much as I can to the notes when publishing a branch. If I learn something when I’m building, I’ll record a short video for myself or even share as part of a showcase or something.

I’d like to get to a point where I can automatically document (as much as I can) how components work e.g. capture attributes, their types, variants, etc., so that it means less writing. I’m not properly documenting anything at the moment, but I should - I moan about this myself in my FT work in Support, so I’m a hypocrite. 😂
@Tom Ireland
Personally, I add as much as I can to the notes when publishing a branch. If I learn something when I’m building, I’ll record a short video for myself or even share as part of a showcase or something.

I’d like to get to a point where I can automatically document (as much as I can) how components work e.g. capture attributes, their types, variants, etc., so that it means less writing. I’m not properly documenting anything at the moment, but I should - I moan about this myself in my FT work in Support, so I’m a hypocrite. 😂
Lee Russel
1 year ago
Haha it is such an easy thing to drop as it takes time and technically it is a completly optional extra! But I know from my work as a PM on really large projects documentation is a life saver. Especially if you have to onboard someone new to the product haha.
@Lee Russel
Haha it is such an easy thing to drop as it takes time and technically it is a completly optional extra! But I know from my work as a PM on really large projects documentation is a life saver. Especially if you have to onboard someone new to the product haha.
Tom Ireland
1 year ago
💯 Working in Support, we have to understand new product versions e.g. new features, improvements, etc., so docs and deep dives are essential! Easy to ignore though. 🫣

Advice/tips for component documentation

Tom Ireland

Lucas G

Lucas G

DarrenBignall

Lucas G

DarrenBignall

Victor Giron

Victor Giron

Tom Ireland

Tom Ireland

Max

Tom Ireland

Max

Tom Ireland

Lee Russel

Tom Ireland

Lee Russel

Tom Ireland