Changing the Introduction #1820
Conversation
|
Note, the links to release information and getting started pages are links to this site currently: https://revamp-the-rabbitmq-home-pag.rabbitmq-website.pages.dev/ I know these need to change. Also what are your thoughts on including a table on this page for the different personas i.e. Developer, Administration ....1 column per persona, then under each persona we could include a linked list to the documentation that each persona would use setup RabbitMQ for that persona??? Thanks |
Deploying rabbitmq-website with
|
| Latest commit: |
8d0b565
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://24a8f7fa.rabbitmq-website.pages.dev |
| Branch Preview URL: | https://revamping-docs-introduction.rabbitmq-website.pages.dev |
|
Starting to organize topics based on the reader’s profile is great! I believe this should be the primary focus of this page. Content such as:
… is ephemeral because it will be obsolete as soon as there is a new version or when we change the ToC. This phrasing is better suited for a blog post. Furthermore, because that page is versioned, maintaining ephemeral content will be difficult. I think the welcome page should remain valid at any time. If we focus on administrators and developers, the page will greatly help people navigate the docs. Also, a table is not suited to present non-tabular data. Sections will be good enough. |
|
Thanks @dumbbell for your feedback, I will add some sections for user profiles. With regard to your comments above, I agree with them yes but I think for now on a new doc site, which users are navigating around/getting used to lets include this information - show them how to use the versioned docs and tell them what is included in them. Yes, it will change in time (new release/changes in TOC) but that won't be for a while....the next RabbitMQ release is not until 4.0 and that is not due out for a long time yet. I will condense it up a bit, remove some of those H2 headings, thanks. |
|
also documentation.md needs to be renamed to index.md before merging. |
|
Hi @dumbbell, @mkuratczyk, and @michaelklishin Can you please review the new doc intro page. Please note this is the initial DRAFT, I need your input now with the list of tasks each persona (admin and developer) would complete to use RabbitMQ. I know it is difficult to do this as the route each persona takes is very much dependant on their own requirements. In the important notes before the tables I am attempting to reiterate this. The layout i.e. current tabular format in HTML will all change as will the the link format (@dumbbell will help me with this when the time comes) so please don't comment on that for now. Right now, we must get the content correct i.e. the general list of tasks a developer and an administrator would complete Please feel free to update in the branch itself. Also, this Another point @dumbbell, when we have the information for these 2 personas in decent shape, perhaps we can link/reference your use cases: https://www.rabbitmq.com/ from this intro page i.e. match up a persona with one of those particular use cases? Many thanks in advance, |
There was a problem hiding this comment.
My general feeling after taking a step back is that the tables generally repeat the table of content. You did a great job with that ToC and it's well organized and already reflects the questions a user (developer or administrator) will have and in the correct order. I'm having second thoughts about a list of tasks each user may go through.
I mean:
- We already have tutorials for developers that cover the basics. After the tutorials, it's hard to predict what the developer will look for because it will be dependant on their use case.
- For admins, the sequence is usually install -> configure -> backup/monitor. Underneath, the order is dependent on the use case as well.
I'm wondering if we should keep the developer and admin sections, but have a simpler paragraph guiding each persona to find the entry point (tutorials for developers, the install page for admins).
Thanks a lot @dumbbell for this feedback, I will take make additional changes to this page based on your comments. I shall have the next iteration out for review by the end of today, thanks. |
|
Hey @dumbbell Can you take a look now, I removed the "Developer" and "Administrator" tables with the list of tasks and instead have 2 paragraphs about these personas under each persona heading. Many thanks |
dumbbell
force-pushed
the
revamping-docs-introduction-page
branch
from
d5a9695
to
3769ba9
Compare
|
@pstack2021: I applied the latest changes we discussed and rebased the branch on top of the latest main. In addition, I used the CSS style sheet to change the paragraphs at the beginning that talks about the drop-down menu and the table of contents. On large screens, they point to the top-right corner and the left sidebar and have icons to make this even more visible. On small screen, when the left sidebar disappears, the paragraphs are replaced to mention the hamburger icon and the main menu. So now, they adapt to what is actually displayed for the user. The preview is available at the same URL: |
dumbbell
force-pushed
the
revamping-docs-introduction-page
branch
3 times, most recently
from
138ae6f
to
0cc057f
Compare
[Why] The previous page only repeated the table of contents. Now that we have a clean, reorganized and easy to access ToC in the left sidebar, we don't need to duplicate the work. [How] The new introduction is now used to welcome users and: - briefly explain the layout and organization of the docs - guide them to the relevant content based on their profile, developer or administrator. The introduction page also reminds the reader about the version of RabbitMQ documentation they are currently viewing.
dumbbell
force-pushed
the
revamping-docs-introduction-page
branch
from
0cc057f
to
8d0b565
Compare
|
Thanks a lot @dumbbell |
Why:
The current introduction page is a table of contents, now that we have a doc table of contents on the new site, we don't need to list links to all the docs on this page. Updating now to provide users with a docs welcome page to help them navigate around this new versioned documentation site.