search

IBM / IFT-Developer-Zone

IFT-Developer-Zone
58 stars 34 forks source link

Sunset GitHub IFT Developer Zone public wiki documentation #30

Closed joshhus closed 3 years ago

joshhus commented 3 years ago

This issue is opened to discuss and approve (or not) the sunset / removal of the devzone IFT public (external) wiki documentation, at:

https://github.com/IBM/IFT-Developer-Zone/wiki

Risks and benefits are described below, and all interested parties are an Assignee.

Once digested, we'll do a call to discuss any questions or concerns.

joshhus commented 3 years ago

Removal of the devzone IFT public (external) wiki documentation - considerations

https://github.com/IBM/IFT-Developer-Zone/wiki

Rationale/benefits:

  1. Reduced Maintenance. -- Removal of duplicate content (that already exists in IFT & BTS docs) reduces maintenance costs.
  2. Better Practice. -- Removal of duplicate content reduces content out-of-sync risks (through elimination of "double-updates").
  3. Improved UX. -- Removal of duplicate content reduces user confusion about master docs source and currency / version.
  4. Improved format. -- Some users prefer the "formatted" or designed look and feel of docs as opposed to code-like GitHub wiki display.

Risks/drawbacks:

  1. Broken links. UI messages and code, Swagger docs, and user bookmarks, all refer to devzone wiki URLs, which would no longer work. Changing code and/or auto-rerouting the clicks to the "new" URL would be required.
  2. Support impact. Support team uses devzone wiki extensively. A change would require them to change environments for user support and opening Issues.
  3. Format change. - Some users, developers perhaps, may prefer the GitHub plain text presentation to colorized and styled/designed documents.

Mitigating factors:

  1. Redundancy exists. -- All to be removed wiki pages (all) already exist, and are fully current with and identical to, the internal private GitHub version of the same GithHub devzone wiki, at https://github.ibm.com/FoodSafety/developer-zone/wiki
  2. More redundancy exists. -- All to be removed wiki pages (all) are already duplicated on the public IFT docs side - at https://food.ibm.com/ift/docs/
  3. Internal wiki. -- Could be kept as a record / reference without further updates, or removed entirely as a "backup" of record.
joshhus commented 3 years ago

duplicate with https://github.ibm.com/FoodSafety/bugs/issues/767