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 > Got it. It looks like this is what's being used to generate the CLI docs -- https://github.com/pwittrock/brodocs. We would suggest moving CLI docs into Redoc so they match the rest of the API doc UI (and reduces the number of frameworks to learn/manage). The solution may become more obvious as my team and I dig into the codebase. We'll add suggested steps to the existing doc next week.
On Tue, Jul 27, 2021 at 4:30 AM Guangning E <eguangn...@gmail.com> wrote: > 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 >> >> -- 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
