PowerPlug Website
renatorib opened this issue · comments
This issue will serve to discuss the powerplug website. It will only be closed when we launch it.
First of all, I like the idea of generating the docs pages with md files as many do.
Also I like the idea of generating docs based on code comments (like JSDoc) but I'm afraid of taking flexibility.
My main idea is to have a beautiful landing (I've already started to draw, but there is still little left.) by interactively presenting powerplug concepts, etc. and having a separate docs page. (for example https://emotion.sh/ but with more content in landing).
For docs: I like the Ramda docs (http://ramdajs.com/docs/). Not the design, but how they structure your information.
@renatorib I'm really excited about this issue. I wanna be a part of it for sure and will help by throwing some ideas about the website and automated docs generation.
I love JSDoc as you do but I think it will limit you on some points. If there is an automated way of doing this that I'm not aware of, please share it.
A beautiful landing page will help in branding React-Powerplug even more. A related and fine designed logo can help as well.
The most thing besides the docs and API reference in the landing page that I care about, is having a good demo/examples page and even a page to introduce what you can do with powerplug. even where to replace powerplug with traditional React component solutions to widen the perspective here.
Even a recipes page as Redux has can help most newcomers get up and running with powerplug even more.
About logo
It was recently redone:
I keep the files in figma
About docs:
I like separating docs in API Reference (more pragmatic, even generated), Guide (more developed, explanatory texts about components, etc) and Recipes (tutorials, examples, use-cases, etc). I think Apollo did a great job doing this, can be a good reference (https://www.apollographql.com/)
Yeah, I think I agree with you. ApolloGraphql has done a very good job on the landscape for sure. even their design is satisfactory to me.
Honestly, Apollo's docs are quite a mess to me. Full of nice information, but not well organized - even after the docs recent rewrite. The site design, though, is quite a good showcase.
I think powerplug is a much more straightforward lib to have issues with organization. A simple repl alongside the docs for each component should do a great job already.
I quite agree that apollo docs is too much for our case. PowerPlug 99% more simple than Apollo indeed.
I mentioned apollo docs because I really like what they do creating that guide/recipe.
The powerplug api is very very simple. A documentation page/site would be too small, simple. However I believe there are many usecases that can be addressed.
I started working on it. If anyone has any suggestions, please tell here =)
Any progress? At least have some simple demos page.. I mean, I need to see some demos before I spend any time downloading and wasting more time integrating something that i'm not sure I would like.
It's like buying cloths online without even an image, just a description :p
