search

zowe / docs-site

Documentation for the Zowe project
https://docs.zowe.org/
Creative Commons Attribution 4.0 International
70 stars 133 forks source link

Investigate the redesign of medium.com/zowe #3209

Closed samanthasusu closed 8 months ago

samanthasusu commented 1 year ago

We will redesign the medium.com/zowe by different Zowe components to better promote the updates and doc enhancement. The redesign will impact medium.com/zowe, zowe.org. and docs.zowe.org.

samanthasusu commented 1 year ago

Zowe medium redesign mockup.pptx

balhar-jakub commented 1 year ago

When you are talking about components it seems that you are actually talking about squads?

Other than that in the redesign we are missing few topics, that I don't know where they would fit:

samanthasusu commented 1 year ago

@balhar-jakub Thanks for bringing this up, Jakub. This idea is originally from @Joe-Winchester and this is actually some feedback from our customers (they talked about this on the conference). So what the customers would like to see is:

  1. The blogs that are categorized by a way that they are familiar with. For example, CLI, APIML, Explroer, App Framework, Installationg and configuration, Zowe incubators (maybe this is the topic for IntelliJ?), etc.
  2. They want to access the blogs on zowe.org as well. For example, currently on zowe.org, when we scroll down to the Zowe project section, we do see some external links to the slack, github repo, etc. But users also want to read the related blogs from this section. So maybe we can add the corresponding entries to each tab under the Zowe project. Screenshot 2023-11-07 at 10 23 04
  3. Apart from the medium blog links, it would be convenient for users if we can put the corresponding video/video playlist link there as well.

If I miss any key points here, @Joe-Winchester please feel free to post the feedback from conference here to share with Jakub. Thank you very much!

balhar-jakub commented 1 year ago

I agree that the structure needs to change and I believe that doing it based on the projects may be a good way.

  1. The current Core Projects that we have are - App Framework, API Mediation Layer, CLI, Explorer for VSCode, Node.js SDK, ZSS and from V3 also Explorer for Intellij. We may on top of that probably add Extensions for the rest e.g. Kotlin SDK, Chat, Zebra, Python SDK, Java SDK, Swift SDK. When we are talking about Incubation than we are talking about squads and therefore mixing terms.
  2. Presenting more details on the specific projects on the zowe.org also seems to be relevant and it makes sense to be able to link to the articles that are relevant to the specific projects.
  3. I agree, do we have such playlists?
samanthasusu commented 1 year ago

@balhar-jakub Currently we only have some related playlists, but we can produce more in the future and add them once it's ready.

Joe-Winchester commented 12 months ago

Thank you @samanthasusu for creating this issue, I've done some digging around and we currently have three feature pages

image

Each page is associated with a tag, for example Zowe Core is associated with the tag zowecore which is set against a blog's topic tag.

image

and then the feature page lets you specify the tag you want to be included in that feature page.

image

We can delete the existing features page and add new features pages (with the New feature page button).

Tags on a blog are free format, and when a blog is reviewed and edit the tag zowecore or zoweecosystem or zoweincubation is added by one of the reviewers. The other four (there are a maximum of 5 tags) are arbitary.

Looking across all of medium.com/zowe the top 10 tags used are: Tso Mainframe Zowe Zowecore System Programming Zowe Open Source Mainframe

image

Joe-Winchester commented 12 months ago

The feedback I've gotten is two fold:

If going forward we could use the tags to match the Zowe Projects Application Framework, API Mediation Layer, CLI,Zowe Explorer VS Code,Zowe Explorer IntelliJ,Zowe SDK,Software Development Kits (SDK),General` (for everything else), and for counting I added a "Server install and config" we get the following historic totals:

image

(Some articles could count twice, for example things that describe team configuration I put against CLI and Zowe Explorer VS Code, and also some things were APIML and CLI where they talked about token based auth.

The one thing I haven't done yet is think about the docs, as there was a request that in certain doc parent chapters we had links to a feature page that pulled together blogs relevent for that specific area of Zowe.

RASakach commented 11 months ago

Thank @Joe-Winchester for bringing this topic to the Onboarding Squad meeting on 12/1. @balhar-jakub , since Onboarding & Doc co-manage the Zowe.org site and any change to the site has potential to impact all Squads, can we please plan a TSC topic (at an upcoming TSC meeting) with an overview of the Problem-to-solve and the proposal for solving it?

balhar-jakub commented 11 months ago

I am adding it to the agenda.

samanthasusu commented 11 months ago

The feedback I've gotten is two fold:

* In the docs we have chapters on specific topics (CLI, VS Code, Server side install and config, ...) and we also have great content (uncategorized) on the medium.com/zowe site.   The ask was that in the doc chapters for high level topics we could have links to feature pages for that topic.

* If a user of the CLI is visiting medium.com/zowe they'd like to maybe see all CLI articles as they are relevant to that user.

* on zowe.org the projects are nicely grouped in tiles with links to github, slack channels, doc learn more, ...   Could there also be a link to the medium.com/zowe articles relevant to that project.

If going forward we could use the tags to match the Zowe Projects Application Framework, API Mediation Layer, CLI,Zowe Explorer VS Code,Zowe Explorer IntelliJ,Zowe SDK,Software Development Kits (SDK),General` (for everything else), and for counting I added a "Server install and config" we get the following historic totals:

image

(Some articles could count twice, for example things that describe team configuration I put against CLI and Zowe Explorer VS Code, and also some things were APIML and CLI where they talked about token based auth.

The one thing I haven't done yet is think about the docs, as there was a request that in certain doc parent chapters we had links to a feature page that pulled together blogs relevent for that specific area of Zowe.

Thank you Joe for the stats. I will figure out the matched doc pages to to these tags and will keep everyone posted.

samanthasusu commented 11 months ago

Group 9 In this design mock-up, take API ML as an example. On zowe.org - Download section, there will be a new entry called "Medium blogs" for users. And if the user click on this link, they will be directed to the page for all APIML related blogs. The similar pattern applies to the rest of the categories. On medium.com/zowe, we will have different sections based on components.

Once the categories are finalized, we need to add some changes to the existing guidelines to remind users of the content for different sections. And all category links for medium.com/zowe will be added to the corresponding doc site pages.

balhar-jakub commented 11 months ago

@samanthasusu This sounds really good. I am fan of the solution you present. I would also add the link to the specific projects to the zowe.org projects area.

samanthasusu commented 10 months ago

All blogs are currently re-categorized on medium.com/zowe. You can access the corresponding featured pages for details.

And we might need to update the corresponding instructions for the blogging guidelines. I will create a pull request for input from anyone who is interested in this.

Joe-Winchester commented 10 months ago

Thank you @samanthasusu for creating the feature pages.
One thing I noticed is that not all of the Zowe Explorer for IBM CICS blogs had the Zoweincubation tag so I've added this to all the ones I could find. They already had Zowe Explorer which is great. Looking forward very much to the homepage having the feature page links and the zowe.org projects having links as well, which will really help different users find their way to the great blog content that exists for the various components.

balhar-jakub commented 10 months ago

Thanks @samanthasusu - That's great job. I really like this. @KUGDev do you want to have a separate space like the other key projects? Right now there will be only one article, though.

samanthasusu commented 9 months ago

blog_guidelines.md @balhar-jakub Thanks Jakub for your review. Would you mind updating the blogging guidelines since we are going to change the navigation content? The attached file is the updated version with my edits, but I believe the community members will have more to add. So I upload it here so that you and the rest of the community can take next steps. Also, if no further comments, I will update the medium.com/zowe on Friday with these changes on the homepage. Thanks!

KUGDev commented 9 months ago

Thanks @samanthasusu - That's great job. I really like this. @KUGDev do you want to have a separate space like the other key projects? Right now there will be only one article, though.

Hi. Yes, it would be great, we don't have much posted yet, probably the situation will change in the future

dkelosky commented 9 months ago

Two questions:

Joe-Winchester commented 9 months ago

Two questions:

  • will the old tags of ecosystem, core, and incubation go away? folks might find these in old blogs which do not align with the new organization
  • can multiple tags be added? some articles cover multiple zowe components, will they be tagged for all of them?

Hi @dkelosky , The old tags are still used and the pages for https://medium.com/zowe/core/home, https://medium.com/zowe/ecosystem/home and https://medium.com/zowe/incubation/home will still exist. What's changed is there these are no longer feature pages (which will be for the new categories Sam describes above). An article can have up to 5 tags, so two of these will be a combination of Core/Ecosystem/Incubation and another to specify the component CLI/APIML/explorer, ... to allow users who are interested in a particular component to narrow their view to relevant content. Depending on the article (which might cover CLI + APIML and be part of Core) this would take 3 tags. The remaining unallocated tags are for the author to decide (e.g. DevOps/Security/mainframe) or a broader topic.

dkelosky commented 9 months ago

Understood thanks @Joe-Winchester ... that's clear. I was a bit concerned for example that we might have a busy start to the article if we did something like:

{Core} {Zowe CLI} {Zowe Explorer} {APIML} When a Zowe CLI (or Zowe Explorer) connects to a z/OS server system, it needs to know information about how to reach the endpoint.

However, it looks like we'll still only have 1 of those type of markers in the beginning of the blog.

samanthasusu commented 9 months ago

@Joe-Winchester Thank you for your explanantion! Yes, we have retagged the published blogs so it should be fine if users want to read the old blogs. And I've sent a draft of the blogging guidelines to Jakub, I believe there will be more instructions for the blogs to be published on medium. And I will soon update the home page with our latest design. Thank you both!

Understood thanks @Joe-Winchester ... that's clear. I was a bit concerned for example that we might have a busy start to the article if we did something like:

{Core} {Zowe CLI} {Zowe Explorer} {APIML} When a Zowe CLI (or Zowe Explorer) connects to a z/OS server system, it needs to know information about how to reach the endpoint.

However, it looks like we'll still only have 1 of those type of markers in the beginning of the blog.

balhar-jakub commented 9 months ago

The PR for blogging_guidelines change is here: https://github.com/zowe/community/pull/2186/files we will agree on it on TSC

samanthasusu commented 8 months ago

The redesign is live now on medium.com/zowe and the guideline is updated.