Discussion of documentation of Vue components

[andrewtavis]

Terms

• [X] I have searched open and closed feature requests
• [X] I agree to follow activist's Code of Conduct

Description

This issue is to discuss and potentially implement the first instances of documentation <docs> blocks within Vue single file components (SFCs). Information on custom blocks can be found here, and info on docs blocks can be found here.

Would be great to get the community's feedback on this and if we'd like to put quick bits on usage in the <docs> blocks :)

Contribution

Would be happy to discuss this with people! Implementing any needed settings changes and adding in the first few <docs> blocks could also be a great good first issue 😊

[andrewtavis]

@ahmedy00, it'd be interesting to get your feedback on this as you've been working with Vue longer than most of us 😊 Have you used <docs> tags before?

[ahmedy00]

@andrewtavis I haven't used the tag in any project before, so I don't have educated guess as to the benefits it can provide. In my opinion it may seem beneficial for new contributors at first glance but it may cause code complexity, readability and compatibility problems in the long run.

[andrewtavis]

Yes, I was thinking about also the need to maintain all of this 🤔 The whole point for Vue is that it has the structure of HTML as a basis and should be easy to understand given good naming criteria. We'll also need to do documentation eventually as well, which is where we'd send people 🤔 My one question is, would there be a way to auto document components? Have you heard of/used anything for that? Would be cool if we could generate something from the code and just make sure that we write proper comments where needed.

[andrewtavis]

Thanks for the feedback!

[andrewtavis]

Not sure if you'd have interest in #424, btw @ahmedy00. I know that you prefer script-template-style, but to me/the team as we're using Tailwind it really does make sense to have template first as we don't have style blocks. If you wanted to set up the linting for that it'd be a lot of help 😊

[ahmedy00]

@andrewtavis The reason I use script-template order is that the VueJS community has been using it more often recently. I understand that this is not a better fit for the activist than the template-script, for the reasons you stated in #424. I would enjoy working for #424

[andrewtavis]

Sounds good, @ahmedy00! Appreciate the feedback that what we're doing makes sense 😊 Feel free to write in #424 and I'll assign you :)

[andrewtavis]

Hey @bmartins-42 👋 I was going to close this issue as @ahmedy00 and I decided against <docs> blocks that this issue was originally about, but then I was thinking that this might be a good place for the discussion of Storybook. @ahmedy00 would be someone I'd want in on the discussion as well. Would you want to use this one to pitch the ideas you had on that?

[bmartins-42]

My idea was to implement a tool like storybook that would let us access components in an UI interface where we can play with props and event. It would also simplify the discoverability of components for dev and non-dev contributors.

There is some plugin/configuration already available for Nuxt, tailwind or i18n.

The downside is that we will need to write/update stories to describe components in storybook. Also, tooling will need some setup configuration/maintenance with package updates.

I have never worked on implementing storybook, so I do not have any personal feedback. If anyone have experience with and could share it, that would be great.

---

Other reading:

https://scalingo.com/blog/guide-storybook-vue-js

[andrewtavis]

Is definitely interesting, @bmartins-42 :) Have you used it before for work or another project?

[andrewtavis]

Ability to link the Figma designs and have them as a tab in the story is soooo clean. Thinking about this, if we're working on a new component we'd potentially be able to make a story for it and link the Figma component and then someone literally has the design sitting there for comparison as they're working on the component and using Storybook for reference. Also making sure that we have designs for all components.

Will check alternatives now to make sure we're doing our homework, but this seems so cool.

[andrewtavis]

There's also a Nuxt module for Storybook :) Puts it right in the DevTools!

Only alternative I saw was Histoire, which should get a look in that it's from a Vue Core Team member. Would allow us to customize it more, but then the integrations aren't there yet.

[andrewtavis]

But also looking at Histoire, really like how easy it is to theme it and the fact that we're just writing Vue Single File Components for the stories 👍👍 Obviously Storybook is more developed, but if we get Histoire in the DevTools and a Figma plugin eventually this could be much easier for us to maintain.

[bmartins-42]

Is definitely interesting, @bmartins-42 :) Have you used it before for work or another project?

Unfortunately no, only read about it.

Ability to link the Figma designs and have them as a tab in the story is soooo clean

I didn't see this part, but indeed this would help a lot. Here are some doc about

If you validate storybook as a documentation, i'm interested to do the setup.

[andrewtavis]

How do you feel about Histoire though, @bmartins-42? Maybe waiting a bit on this until they get auto documentation up could be something? I'm not expecting it'll be too long off 🤔 I could contact the maintainers and see if they could provide an estimate on that, if that's the main thing we're missing.

I'm just a bit worried about unnecessarily adding a different syntax into the codebase when there is something that does job and uses our current technologies. We could very easily make good first issues for people to document the components where they're just writing a Vue SFC, then afterwards they're also ready to actually start contributing code to the project.

I don't think that this is something we can decide on before the next dev sync on the 4th, so I'll plan on bringing it up then! You'd be more than welcome to attend! Details will be on Matrix 😊

[andrewtavis]

And thank you so much for the offer to set up Storybook! Really appreciate the willingness to take on such a large task 🚀 Let's figure this out and get some great documentation out that can help new people come in and build great things!

[bmartins-42]

So I did take a look at Histoire, it's promising, but I don't think it's ready yet (lot of issue, few plugins, beta API). I also regret the fact they didn't leverage SFC with or tag in template, but it's probably due to the way SFC is transformed.

I understand your concern about creating syntax for storybook, especially if we want the documentation to be a gate for newcomers. I guess we need to discuss furthermore or make a POC to compare the result.

I will try to attend the next dev sync :)

[andrewtavis]

Great that you'll try to be at the next sync, @bmartins-42! Already have this point typed into the topics for discussion 😊 Let's be in touch on this, and if it means we need to wait for a bit to see if Histoire develops a bit then we can wait. Aside from this we can of course use Storybook if the need becomes more immediate.

[andrewtavis]

Checked out Histoire again given that Nuxt Devtools just hit v1.0 a bit ago. There's still no module for Histoire, but it does appear to be on the roadmap for the organization as in the 1.0 release docs they're mentioning integrations between the dev tools and Histoire 😊

[jb90000]

Hey @andrewtavis, I notice this issue is tagged as good for first-timers so I'm chiming in here! I see lots going on in the comments here - is there any work left outstanding on this issue that requires documentation support?

[andrewtavis]

Hey @jb90000 👋 This would be something good to work on at some point, but we're a bit blocked with other issues at the moment. What's needed here is to test the setup we have for Histoire and then to start making the first frontend component stories. I'd be happy to explain more if that'd be something you'd be interested in working on :)

[jb90000]

Thanks, @andrewtavis ! Would those tasks be suitable for a non-technical first-timer? If so, I'd love to learn more.

For context, I'm a writer making my foray into GitHub as a way of practicing docs as code flows.

[andrewtavis]

Yes, they certainly would be! Give me a moment to get back from vacation and a few weeks to get the MVP out, but then we can start with this? I can also give it a look next weekend and see if the baseline can get up and running :)

[jb90000]

Sounds great - enjoy the rest of your vacation!

[jb90000]

Hey @andrewtavis, figured I'd follow up here to see if this is still on your radar. I know you mentioned next steps would be to test the Histoire setup and then to start making the first frontend component stories.

Let me know if there's anything I can do to help get things started!

[andrewtavis]

Appreciate you checking in here, @jb90000! Let me get through the current PRs and we should be good to start looking into this :) Hopefully next week?

[jb90000]

Sounds great, @andrewtavis - I'll keep an eye out for your response!