New documentation site #32
Conversation
|
The idea is a good one. Thanks! What I would do would be to move all these sections of the README:
Once it's moved, I will simplify the README and put the badge and link to the documentation. |
|
The glad you like the idea. Yes, I was thinking to do the same, move each section to the documentation site and then simplifying the README.md 💯 |
|
Hi! I think is a good move to put all the docs in a website. Do you know if you can put a version selector on docs? I mean, it could help in the future to document the versions of the library over the time. Nice proposal Siddarth |
|
Thank you @danielart! It would definitely be helpful to document versions of the library over time, for now I am focusing on the current version and but I will keep in mind how to implement versioning for this. |
|
Great @siddharthborderwala ! and just give you more ideas, we talked with @aralroca could be interesting to have gtm tracking to see which pages are the most visited, to detect where community have more interest/doubts, and may be a vote component on some pages, just like nextjs have on his docs at the bottom on each page https://nextjs.org/docs. May we can help you with that. Thanks for your efforts 💪 |
|
That would be interesting, so voting with Google Tag Manager itself, right? |
|
I'd like to mention that as the number of features in this doc site increases, time taken for implementation will increase from my side, as I am a full-time university student 👨🎓 |
|
@siddharthborderwala were ideas for the future. For this PR with what you are doing it is more than useful! Everything can be done in several iterations after merging this PR, we can contribute several in the documentation, no problem 😊 |
add Input Params and Return Value sub-heading
|
@danielart @aralroca I personally believe that we should avoid adding everything from scratch. @siddharthborderwala Has done the wonderful job in this part. Ideally we should go for more stable static site generator, which handle most of the things from out of the box for us. We should not spent more time adding things which are already done by other third party library. I would suggest to go for some static site generator like (docusaurus)[https://docusaurus.io]. It is doing already on behalf of us and it handle lot of cases automatically which we need not to worry. There community is quite good. If we want to customize everything via our own. Than its good idea to make everything from scratch than we can go with this. For reference you can go to this: https://ydkjs.netlify.app Here is docusaurus showcase: https://docusaurus.io/showcase I am open for feedback. Check and see if this can also work. |
@shubhamV123 Looks good for me, we talked about some interesting features. I don't know docusaurus in deep, but do you know if allow to keep docs by library version? and could we add a widget to vote if a page is useful as nextjs do in their docs? |
@danielart Q. Can we keep docs by library version? Q. Could we add a widget to vote if a page is useful as nextjs do in their docs? |
|
My take @shubhamV123 @danielart @aralroca -
|
|
One more thing I found out @siddharthborderwala . You are using nextra for markdown. Its not a production ready. They mentioned clearly on there doc : So if you want to use it, use another mdx compiler like remark or something similar to that which is production ready |
|
Nextra is a static-site generator, for e.g. like gatsby, and it uses mdxjs behind the scenes for parsing md and mdx files, which is battle-tested. So, nextra as a static-stire generator may change in the future, but the mdx related stuff will still be the same as it dependes on mdxjs. |
|
Agree. But there must be reason that's why they clearly mentioned Whats your thought on this @aralroca @danielart ? |
|
@siddharthborderwala @shubhamV123 in this stage of teaful (in early development, growing fast) we have to check some possibilities and try to get the best choice. Bear this in mind, instead of develop the whole docs for teaful, we could try to have a very small mvp with each option, and then compare them and maybe ask community their opinion, maybe in the discussions tab. I usually pick the most used option for this kind of things, but as we are a new library behind 1.0, I think is fair to give a try to nextra, at least to check a mvp. |
Make sense if this works, we can go for this than. |
|
Yes, it is mentioned that nextra is not ready for production but it is being used for the documentation of SWR library built by a team at vercel. Moreover, nextra is backed by vercel. Also, the API has been stable for quite some versions and in that aspect it is a safe bet to say that the API won't change drastically, leading to a lot of changes from our side. Adding to this, the currrent API seems very standard from the viewpoint of static-site-generators. I think nextra is a good contender here and personally I feel docusauras is used at a lot of places, it would be nice to have a different kind of documentation, with some minimalism, just like the library itself. |
|
@danielart @aralroca I have implemented the feedback-rating (without the backend) component. You may have a look at it on any page of the docs. It'll be easy to integrate with google-analytics events or tag manager. |
|
@siddharthborderwala Looks good for me! let us know if you need help with that. Thanks for your efforts 💪 You're awesome ! |
Yes I'll let you know once we need to setup analytics using a google account. I'm glad I could be helpful! Thanks 😃 |
|
@danielart @aralroca The docs site is updated with latest docs content. It is almost complete, two things left -
|
|
Let's plan to release the website with the 1.0.0 version! |
|
thanks for your efforts! great job @siddharthborderwala, do you need help with that? |
|
@siddharthborderwala It's incredible! Very great contribution! I've looked at both the code and the result and it has my approval 👏 When it's all changed from "Draft" to "Ready for review" I will look at it in more detail. But it's great for me. Do you need help with Google Analytics or anything? |
|
@danielart I don't think I need any assistance, I just want to know which google account to use to setup the analytics. Maybe, @aralroca can create a property on google analytics and then he can give me the credentials required to be able to use ga library for the web. |
|
@danielart @aralroca Added google analytics with custom feedback event. |
It is done 😄🎉 |
|
@danielart @aralroca have a look at the completed documentation site. Let's decide on what other content should be added on the docs. |
|
@siddharthborderwala IMO this is a very great contribution, all you did here deserves to be merged now! I reviewed and is perfect. Thanks for everything! And welcome as a contributor. Maybe in more iterations, we can improve the documentation. Before deleting the README documentation to replace it with this one it would be nice to choose which version of Teaful is showing the documentation. |
|
@all-contributors please add @siddharthborderwala for documentation, infrastructure and code |
|
I've put up a pull request to add @siddharthborderwala! 🎉 |
|
Thank you @aralroca I am super excited to have contributed to teafuljs! Yes, thinking ahead, it would be a great idea to consider versioning too. This docs site is for the 0.7 version. |
I have setup a documentation site for this library. I am using nextjs and nextra starter for creating a static documentation site.
The docs directory contains the next-js app, it uses yarn, keeping the package manager uniform.
Currently, I have only created 2 pages of documentation, you can have a look at it - https://teaful-docs.vercel.app/.
Let me know what you think @aralroca