If content from both the REST API and CLI are being folded into docs, then we would only need to create one design template for docs vs. 3 templates - 1 for docs (Docusaurus), 1 for REST-API (is this in Docusaurus?), 1 for CLI is this Redoc, Docusaurus or something else?). Does that help?
Yes, there are currently three page styles, the rest-api uses redoc, the cli uses a style similar to kubectl, and the main site's docusuraus style, but we will consider unifying their styles, and I think in the future they will use a unified style Melissa Logan <meli...@constantia.io> 于2021年7月27日周二 上午11:23写道： > REST API and CLI docs are automatically generated from code, what kind of > "template" for them do you refer to? > > By “template” I mean a design template to create a uniform look and > feel for the site. The REST API and CLI docs each have their own look and > feel with Redoc being used for the API pages. Our aim would be to create a > unified look and feel throughout the site, including those pages. > If content from both the REST API and CLI are being folded into docs, then > we would only need to create one design template for docs vs. 3 templates - > 1 for docs (Docusaurus), 1 for REST-API (is this in Docusaurus?), 1 for CLI > is this Redoc, Docusaurus or something else?). Does that help? > > Agree. SEO is important as it improves user experience, making it more > likely for users to become repeat buyers. So any plan for the research? > > Our team will conduct an SEO audit to understand what needs improvement > and make suggestions. > > On Mon, Jul 26, 2021 at 5:53 AM Anonymitaet _ <anonymita...@hotmail.com> > wrote: > >> Hi Melissa, >> >> Many thanks for your suggestions! I've replied to you in the google doc, >> PTAL. >> >> #1 >> >> *Based on what we see today, there would be 8-10 new templates to create* >> * (homepage, landing, general, library, events, blog landing, blog, and >> docs -- and possibly a template for REST API and CLI Pulsar Admin, unless >> the latter two will be merged into docs) -- for which we could contribute >> design and development.* >> >> REST API and CLI docs are automatically generated from code, what kind of >> "template" for them do you refer to? >> >> >> - REST API doc example: >> https://pulsar.apache.org/admin-rest-api/?version=2.8.0&apiversion=v2 >> - >> - CLI doc example: >> https://pulsar.apache.org/tools/pulsar-admin/2.8.0-SNAPSHOT/ >> >> >> #2 >> >> >> *One consideration brought up on a previous thread [3] was SEO. We would >> conduct research on keywords and update content to be relevant (with the >> priority being meaningful content to end users first, SEO second).* >> >> Agree. SEO is important as it improves user experience, making it more >> likely for users to become repeat buyers. So any plan for the research? >> >> #3 >> >> >> >> >> >> *Wonderful! Agree with what you say here. I have added a suggested >> navigation to the doc though still have a few questions about if/whether it >> makes sense to merge the REST-API section and/or the CLI>Pulsar-Admin >> section into docs. That can be determined later, but wanted to mention as >> an open question. Please note these recommendations are in absence of >> seeing the analytics, which may affect page orders.* >> >> We're re-structuring the information architecture of docs and planning to >> put "REST API" and "CLI" docs to the "Reference" chapter. We'll send it out >> for discussion once we finalize it. >> >> #4 >> >> >> >> >> *Absolutely, our team will work with Docusauraus as the >> community-approved framework. It also looked like something called Redoc >> might be in use (mentioned in the REST-API section). Is this framework also >> being used or should that be brought into Docusaurus? Are both front-end >> and back-end design/development needed? We can do either/or.* >> >> @Guangning E <eguangn...@gmail.com>, any thoughts on this? >> >> >> >> ------------------------------ >> *From:* Aaron Williams <aaron.willi...@datastax.com> >> *Sent:* Saturday, July 24, 2021 03:03 >> *To:* Dev <dev@pulsar.apache.org> >> *Subject:* Re: [Doc] Upgrade Docusuraus >> >> One of the missing pieces to the design of the current website is the >> journey of the visitor. Is this their first time, if so what do they >> need? Is this their 10th time and they are looking for documentation? >> >> We need a better, cleaner, easier to use website. >> >> The above is a longer version of saying >> >> +10! >> >> >> >> > >> > >> > Hi, >> > >> > I'm a new contributor to the Pulsar community. My team and I recently >> > rebuilt the Apache Cassandra website [1] with the aim of improving user >> > experience and SEO to help visitors more easily understand and use >> > Cassandra. Based on recent threads here [2] and here [3], it appears the >> > Pulsar community has similar aims. >> > >> > My team and I have decades of experience building sites with expertise >> > working with open source projects. We are offering to contribute 2-3 >> design >> > concepts for the community to vote on that will create a uniform design >> > pattern to the site. >> > >> > Based on what we see today, there would be 8-10 new templates to create >> > (homepage, landing, general, library, events, blog landing, blog, and >> docs >> > -- and possibly a template for REST API and CLI Pulsar Admin, unless the >> > latter two will be merged into docs) -- for which we could contribute >> > design and development. >> > >> > Would these contributions be of interest to the community? We are >> standing >> > by to participate upon consensus. >> > >> > Additional thoughts/questions: >> > >> > One consideration brought up on a previous thread [3] was SEO. We would >> > conduct research on keywords and update content to be relevant (with the >> > priority being meaningful content to end users first, SEO second). >> > >> > Does the site currently have analytics? That will help us understand >> how to >> > best approach IA and content updates. If not, we previously recommended >> the >> > open source Plausible.io analytics platform (uses an Apache license) to >> > Cassandra, which is acceptable for use by any ASF project. [4] >> > >> > We will add a suggested IA to the redesign doc. [5] >> > >> > Melissa >> > >> > [1] https://cassandra.apache.org/ >> > [2] >> > >> > >> https://lists.apache.org/x/thread.html/ra618c666d52f518741f64313969a9f16f20b8f06cd444f499f77cd93@%3Cdev.pulsar.apache.org%3E >> > [3] >> > >> > >> https://lists.apache.org/x/thread.html/rbc6c15e936c3916ba989a2057670344a2b82f5aa7812c379d95a2862@%3Cdev.pulsar.apache.org%3E >> > [4] https://issues.apache.org/jira/browse/CASSANDRA-16488 >> > [5] >> > >> > >> https://docs.google.com/document/d/1IV35SI_F8G8cL-Vuzknc6RTGLK9_edRMpZpnrHvAWNs/edit# >> > >> > On Mon, Jul 19, 2021, 18:01 Anonymitaet _ <anonymita...@hotmail.com> >> > wrote: >> > >> > > Hi all, >> > > >> > > Just a gentle reminder: >> > > >> > > If you have any suggestions on the Pulsar website, do not hesitate to >> > > leave your comments here ( >> > > >> > >> https://docs.google.com/document/d/1IV35SI_F8G8cL-Vuzknc6RTGLK9_edRMpZpnrHvAWNs/edit# >> > ) >> > > before EOD July 28 (GMT +8). >> > > >> > > Thanks! >> > > >> > > On 2021/7/14, 11:48, "Anonymitaet _" <anonymita...@hotmail.com> >> wrote: >> > > >> > > Hi all, >> > > >> > > Thanks for the discussion. >> > > >> > > Before upgrading Docusaurus, we've collected some requirements >> from >> > > community and documented here: >> > > >> > >> https://docs.google.com/document/d/1IV35SI_F8G8cL-Vuzknc6RTGLK9_edRMpZpnrHvAWNs/edit# >> > . >> > > >> > > >> > > Feel free to add more if you have any ideas before EOD July 28 >> (GMT >> > > +8). >> > > >> > > After that, we can take all factors into consideration and make a >> > > suitable upgrading plan, thanks! >> > > >> > > On 2021/7/14, 04:42, "Sijie Guo" <guosi...@gmail.com> wrote: >> > > >> > > Hi Aaron, >> > > >> > > Thank you for bringing this up! >> > > >> > > As part of the docusuras discussion, we have already put >> > together a >> > > proposal/plan to revamp the Pulsar website. We are planning to >> > send >> > > out the proposal to the community for review and discussion >> in a >> > > couple of days. >> > > >> > > Would love you to help review the proposal once we send it >> out. >> > > >> > > - Sijie >> > > >> > > On Tue, Jul 13, 2021 at 12:31 PM Aaron Williams >> > > <aaron.willi...@datastax.com> wrote: >> > > > >> > > > Hello Anonymitaet, PMC, and Pulsar Community, >> > > > >> > > > I love the idea, anything that enables new developers to get >> > > started while making life easier for them, our current contributors, >> and >> > > tech writers is a great idea. >> > > > >> > > > >> > > > >> > > > I would propose that we take this as an opportunity to go >> one >> > > step farther and overhaul the entire website. >> > > > >> > > > As we all know, the current one has a number of issues, for >> > > example: >> > > > >> > > > The Home page isn’t visually appealing and doesn’t tell you >> > what >> > > Pulsar is. >> > > > >> > > > Some examples of other Apache product landing pages: >> > > > >> > > > Kafka: https://kafka.apache.org/ >> > > > >> > > > RocketMQ: http://rocketmq.apache.org/ >> > > > >> > > > Cassandra: https://cassandra.apache.org/ >> > > > >> > > > >> > > > >> > > > These are similar projects, but their sites are much more >> > > engaging than ours and leaves the visitor with a better impression of >> > what >> > > those projects do. Plus from other conversations, it is tough to get >> > > metrics from the site. >> > > > >> > > > >> > > > >> > > > For an example of a technical issue: when you mouse over the >> > > tabs they do not open and when you click on the triangles the tab >> opens >> > but >> > > will not close until you click on it again, so you can end up with >> > > something like this (if the image isn’t below, go to >> pulsar.apache.org >> > > and just click on the triangles) >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > There are other issues like not having YouTube videos, >> > > testimonials from users, etc. (we each can come with a couple more >> > issues). >> > > > >> > > > >> > > > >> > > > So following the Apache Community mantra of if you raise an >> > > issue, you are volunteering to fix it. With the PMC’s approval, I am >> > > volunteering to organize a group to revamp our website and the >> > surrounding >> > > collateral. The group will meet to gather specs and create a mock up >> and >> > > report back to the PMC and the larger Pulsar community; take feedback >> > > (using fail-fast/ agile methodology) and improve the design. >> > > > >> > > > >> > > > >> > > > Thank you for taking the time to read this and I look >> forward >> > to >> > > working with the community to improve our window to the world. >> > > > >> > > > >> > > > >> > > > Thanks, >> > > > >> > > > Aaron Williams >> > > > >> > > > >> > > > >> > > > About Me: >> > > > >> > > > Since this is my first time posting and I thought that I >> would >> > > introduce myself. I am at DataStax and their community manager for >> > > streaming, with one of my major goals to help out with the Pulsar >> > > Community. I came from the Linux Foundation’s Edge Umbrella project >> > > (LFEdge.org) and its 10 projects, where I was the Community Manager/ >> > > Developer Advocate, working to grow and strengthen their community. >> > Before >> > > that, I was the Global Lead for SAP’s internal makerspace and >> community >> > > space called the d-shop, where we had over 30 locations around the >> world. >> > > Thus working with communities is what I have done for the last 10 >> years >> > of >> > > my career. And I look forward to working with all of you and helping >> to >> > > grow this community. >> > > > >> > > > >> > > > >> > > > On Tue, Jul 13, 2021 at 6:52 AM Guangning E < >> > > eguangn...@gmail.com> wrote: >> > > >> >> > > >> +1 >> > > >> >> > > >> Enrico Olivelli <eolive...@gmail.com> 于2021年7月13日周二 >> 下午4:14写道： >> > > >>> >> > > >>> +1 >> > > >>> >> > > >>> Enrico >> > > >>> >> > > >>> Il giorno mar 13 lug 2021 alle ore 10:12 Sijie Guo < >> > > guosi...@gmail.com> ha scritto: >> > > >>>> >> > > >>>> +1 >> > > >>>> >> > > >>>> On Mon, Jul 12, 2021 at 8:25 PM Anonymitaet _ < >> > > anonymita...@hotmail.com> wrote: >> > > >>>> > >> > > >>>> > Hi Pulsar enthusiasts, >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > Nowadays, Pulsar grows rapidly, docs are in increasing >> > > demands. While some users have a hard time finding what they need or >> > > encountering other issues. >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > As a sustainable community, we always give the same >> care >> > to >> > > docs as code. To improve the UX, may we suggest upgrading the Pulsar >> > > website framework (Docusuraus) and re-architecture the doc structure? >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > # Issue >> > > >>>> > >> > > >>>> > Currently, the Docusuraus version is 1.11, which is an >> old >> > > version released in 2019. With this version, we cannot customize >> features >> > > based on our needs (for example, navigation is a cornerstone for the >> > site. >> > > We want to optimize it but cannot add more levels for it or collapse >> it, >> > > etc). >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > # Solution >> > > >>>> > >> > > >>>> > Upgrade Docusuraus from 1.11 to the latest version >> (2.x). >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > # Benefit >> > > >>>> > >> > > >>>> > Difference between 1.11 and 2.x: >> > > >>>> > >> > > >>>> > 1.11 is a pure documentation site generator, using >> React >> > as >> > > a server-side template engine, but not loading React on the browser. >> > > >>>> > 2.x, rebuilt from the ground up, generates a >> > > single-page-application, using the full power of React in the >> browser. It >> > > allows for more customizability but preserved the best parts of 1.11 - >> > easy >> > > to get started, versioned docs, and i18n. Beyond that, the latest >> version >> > > is a performant static site generator and can be used to create common >> > > content-driven websites (e.g. Documentation, Blogs, Product Landing >> and >> > > Marketing Pages, etc) extremely quickly. For how to upgrade, see >> > > https://docusaurus.io/docs/migration/automated >> > < >> https://urldefense.proofpoint.com/v2/url?u=https-3A__docusaurus.io_docs_migration_automated&d=DwMFaQ&c=adz96Xi0w1RHqtPMowiL2g&r=xfJCHpjPTxraruLs_Uk3E942RLPiuaa4M5tzdGOlGPw&m=kSAgZQslCRcahlhjNQfLpOmpPJx8Ftd4CJahWyoKnHc&s=uH7tvDG__HYCYPzgzm4wCdHENY5tY6yVH9bny1j660o&e= >> > >> > . >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > If there is a better tool or any other suggestions, >> feel >> > > free to comment. We'd love your feedback, thanks! >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > Anonymitaet >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >>>> > >> > > >> > > >> > > >> > > >> > > >> > >> > > > -- > Melissa Logan (she/her) > Principal, Constantia.io > meli...@constantia.io > Cell: 503-317-8498 > LinkedIn <https://www.linkedin.com/in/mklogan/> | Twitter > <https://twitter.com/Melissa_B2B> > > Schedule a meeting: https://calendly.com/constantia_melissa > >
