search

zowe / docs-site

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

Change titles to articles: Developer Tutorials > Onboard REST APIs..... #149

Closed JamesBauman closed 5 years ago

JamesBauman commented 5 years ago

In the Dev tutorials section of the docs-site, a suggestion was made by a participant during the playback on October 15, 2018. The suggestion is to shorten the names of the topics, they are currently too wordy, which makes the use case unclear.

We are recommending the following changes to the article titles:

From: Onboard an existing Spring Boot REST API service with Zowe API Mediation Layer To: Java REST APIs with Spring Boot  

From: Onboard an existing Java REST API service without Spring Boot with Zowe API Mediation Layer To: Java REST APIs without Spring Boot 

From: Onboarding an existing Java Jersey REST API service To: Java Jersey REST APIS 

From: Onboard an existing REST API service with the Zowe API Mediation Layer without code changes To: REST APIs without code changes

Note: For consistency, we are appending -ing to Onboard in the section heading Onboard REST APIs to the APIML. We apply the fix in the the config.js file, 

title: '**Onboard** REST APIs to the API Mediation Layer',
          collapsable: true,
          children: [
            'api-mediation-onboard-a-sprint-boot-rest-api-service', 
            'api-mediation-onboard-an-existing-java-rest-api-service-without-spring-boot-with-zowe-api-mediation-layer', 
            'api-mediation-onboard-an-existing-java-jersey-rest-api-service', 
            'api-mediation-onboard-an-existing-rest-api-service-without-code-changes']
janan07 commented 5 years ago

I have discussed these title changes with our PO and, for the most part, we agree with the proposed titles. Two changes that we suggest are:

  1. A clearer title for the parent article is, "Onboard existing REST APIs with the API Mediation Layer"
  2. A clearer title for the last title on the list is "REST APIs without code changes required"

As a general note, removing the word "Onboard" from the article titles also makes the purpose of each independent article much less clear as the purpose of the articles is dependant on the title of the parent article.

JamesBauman commented 5 years ago

Hi Andrew @janan07 - As for the parent article title.... Please use "Onboarding." IF this was docops content, Onboard is OK.. However, we have an agreed style with IBM/Rocket to append -ing to all article titles that start with a verb. Also, the other parent articles in this section start with a gerund. so this is also a matter of consistency.

thx, jb

janan07 commented 5 years ago

Thanks for the feedback, Jim. Sounds good.

nannanli commented 5 years ago

All PRs are merged. Can we close this issue now? @JamesBauman @janan07