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.
Yes, it is based on brodoc to generate I think the cli doc(markdown file) and the rest API(JSON file) are two different things. brodoc has been verified to be successful in the kubernetes community, redoc has been verified to be successful for generating the rest api, and I don't think forcing the two different things together is the right approach. Most contributors don't need to know about the this content, they just need to update the annotations in the source code and the content rendered on those pages will be handled automatically. Of course, we can try to make sure they have a consistent style, but this is only a page style (css) change. Melissa Logan <meli...@constantia.io> 于2021年7月30日周五 下午11:05写道： > 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 > >
