From 37438d7b53f166a96bbcafb4fff93210a64a3d7b Mon Sep 17 00:00:00 2001 From: Vladimir Hasko Date: Tue, 7 Feb 2023 15:29:25 +0000 Subject: [PATCH] Fixing some formatting issues --- ..._can_handle_all_documents_in_one_place.rst | 6 ++++- ...rt_back_to_a_previous_document_version.rst | 8 +++++- ...ay_we_have_a_separate_session_for_that.rst | 2 +- ...o_add_a_comment_for_a_text_or_an_image.rst | 4 ++- ...browser_which_button_should_i_click_on.rst | 4 ++- ...nge_with_the_base_modified_text_images.rst | 4 ++- ...o_notify_huawei_that_we_need_an_update.rst | 8 +++++- ...mething_new_doc_or_modify_existing_doc.rst | 2 +- ...uments_can_be_found_per_each_component.rst | 5 +++- ...and_the_current_tasks_or_raised_issues.rst | 25 ++++++++++++++++++- ..._it_or_it_is_coming_from_another_squad.rst | 3 ++- ...a_component_in_the_next_delivery_cycle.rst | 10 +++++++- 12 files changed, 69 insertions(+), 12 deletions(-) diff --git a/doc/source/internal/helpcenter_training/faq/are_there_any_plans_to_move_other_documents_cdr_hld_and_pd_as_well_to_the_platform_so_we_can_handle_all_documents_in_one_place.rst b/doc/source/internal/helpcenter_training/faq/are_there_any_plans_to_move_other_documents_cdr_hld_and_pd_as_well_to_the_platform_so_we_can_handle_all_documents_in_one_place.rst index 87a6f6c..db8193f 100644 --- a/doc/source/internal/helpcenter_training/faq/are_there_any_plans_to_move_other_documents_cdr_hld_and_pd_as_well_to_the_platform_so_we_can_handle_all_documents_in_one_place.rst +++ b/doc/source/internal/helpcenter_training/faq/are_there_any_plans_to_move_other_documents_cdr_hld_and_pd_as_well_to_the_platform_so_we_can_handle_all_documents_in_one_place.rst @@ -2,4 +2,8 @@ Are there any plans to move other documents CDR, HLD, and PD as well to the platform so we can handle all documents in one place? ================================================================================================================================= -Yes, the plan for this year is: Start integration of Hybrid Documentation to Help Center 3.0. Kevin Heyong has already confirmed that he initiates the talks to R&D. Start integration of internal Huawei documents to Help Center 3.0 (this will be a bit challenging as this sort of documents are not present in Huawei documentation system and R&D is taking care of them by their own so the only existing source of the documentation is doc word type) +Yes, the plan for this year is: + + Start integration of Hybrid Documentation to Help Center 3.0. Kevin Heyong has already confirmed that he initiates the talks to R&D. + + Start integration of internal Huawei documents to Help Center 3.0 (this will be a bit challenging as this sort of documents are not present in Huawei documentation system and R&D is taking care of them by their own so the only existing source of the documentation is doc word type) diff --git a/doc/source/internal/helpcenter_training/faq/how_can_we_revert_back_to_a_previous_document_version.rst b/doc/source/internal/helpcenter_training/faq/how_can_we_revert_back_to_a_previous_document_version.rst index 13ad1ef..257479c 100644 --- a/doc/source/internal/helpcenter_training/faq/how_can_we_revert_back_to_a_previous_document_version.rst +++ b/doc/source/internal/helpcenter_training/faq/how_can_we_revert_back_to_a_previous_document_version.rst @@ -2,4 +2,10 @@ How can we revert back to a previous document version? ====================================================== -In git the revert action would mean just another PR with changes pushing the document to previous state. To minimize revert situations both Gitea/Github represents 3 phases of validatiing the documentation. Automated check jobs which validate syntax, conversion and build possibility of the documentation change. Manual approval based on QA/UAT review. Labelling the PR with Gate Label which is only applicable when previous 2 conditions are succefully completed. (Final Gate label will initiate auto-merge jobs and final publishing of the documentation change to Help Center portal). Squad can decide that this final "Go" can be triggered by different person only delegated for releasing activities. +In git the revert action would mean just another PR with changes pushing the document to previous state. To minimize revert situations both Gitea/Github represents 3 phases of validatiing the documentation. + + Automated check jobs which validate syntax, conversion and build possibility of the documentation change. + + Manual approval based on QA/UAT review. + + Labelling the PR with Gate Label which is only applicable when previous 2 conditions are succefully completed. (Final Gate label will initiate auto-merge jobs and final publishing of the documentation change to Help Center portal). Squad can decide that this final "Go" can be triggered by different person only delegated for releasing activities. diff --git a/doc/source/internal/helpcenter_training/faq/how_do_we_deal_with_open_tickets_may_we_have_a_separate_session_for_that.rst b/doc/source/internal/helpcenter_training/faq/how_do_we_deal_with_open_tickets_may_we_have_a_separate_session_for_that.rst index 2ee86a1..f6a685b 100644 --- a/doc/source/internal/helpcenter_training/faq/how_do_we_deal_with_open_tickets_may_we_have_a_separate_session_for_that.rst +++ b/doc/source/internal/helpcenter_training/faq/how_do_we_deal_with_open_tickets_may_we_have_a_separate_session_for_that.rst @@ -2,4 +2,4 @@ How do we deal with Open tickets? May we have a separate session for that? ========================================================================== -Process squad has been asked to move all open tickets to Ecosystem squad. Most of them are already solved or obsolete. + Process squad has been asked to move all open tickets to Ecosystem squad. Most of them are already solved or obsolete. diff --git a/doc/source/internal/helpcenter_training/faq/how_to_add_a_comment_for_a_text_or_an_image.rst b/doc/source/internal/helpcenter_training/faq/how_to_add_a_comment_for_a_text_or_an_image.rst index 2f5eff2..8f43244 100644 --- a/doc/source/internal/helpcenter_training/faq/how_to_add_a_comment_for_a_text_or_an_image.rst +++ b/doc/source/internal/helpcenter_training/faq/how_to_add_a_comment_for_a_text_or_an_image.rst @@ -2,4 +2,6 @@ How to add a comment for a text or an image? ============================================ -As natively in Gitea/Github any change in PR can be raised as a comment and can become subject for requesting the change In case you want to comment something not being subject of change in PR but still valuable to comment (other part of documentation) you can raise an issue for that. +As natively in Gitea/Github any change in PR can be raised as a comment and can become subject for requesting the change + +In case you want to comment something not being subject of change in PR but still valuable to comment (other part of documentation) you can raise an issue for that. diff --git a/doc/source/internal/helpcenter_training/faq/how_to_check_the_rendered_html_of_the_entire_document_in_the_browser_which_button_should_i_click_on.rst b/doc/source/internal/helpcenter_training/faq/how_to_check_the_rendered_html_of_the_entire_document_in_the_browser_which_button_should_i_click_on.rst index 32e44ce..445e803 100644 --- a/doc/source/internal/helpcenter_training/faq/how_to_check_the_rendered_html_of_the_entire_document_in_the_browser_which_button_should_i_click_on.rst +++ b/doc/source/internal/helpcenter_training/faq/how_to_check_the_rendered_html_of_the_entire_document_in_the_browser_which_button_should_i_click_on.rst @@ -2,4 +2,6 @@ How to check the rendered HTML of the entire document in the browser (which button should I click on)? ====================================================================================================== -In the document PR (for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls) search for the latest documentation check job result (for example build-otc-umn) if it's older than one week please add comment in PR "recheck" which will trigger new check jobs and will pre-render documentation again. If it's actual (not older than one week) click on the job, then click on artifacts then click on docs preview site and you should appear on pre-rendered HTML documentation. service doc PR -> Conversation -> build jobs (build-otc-api-ref, build-otc-umn, otc-tox-docs) -> Artifacts -> Docs preview site -> choose doc type -> HTML +In the document PR (for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls) search for the latest documentation check job result (for example build-otc-umn) if it's older than one week please add comment in PR "recheck" which will trigger new check jobs and will pre-render documentation again. If it's actual (not older than one week) click on the job, then click on artifacts then click on docs preview site and you should appear on pre-rendered HTML documentation. + +service doc PR -> Conversation -> build jobs (build-otc-api-ref, build-otc-umn, otc-tox-docs) -> Artifacts -> Docs preview site -> choose doc type -> HTML diff --git a/doc/source/internal/helpcenter_training/faq/how_to_compare_the_content_of_a_change_with_the_base_modified_text_images.rst b/doc/source/internal/helpcenter_training/faq/how_to_compare_the_content_of_a_change_with_the_base_modified_text_images.rst index 47c8bca..4302100 100644 --- a/doc/source/internal/helpcenter_training/faq/how_to_compare_the_content_of_a_change_with_the_base_modified_text_images.rst +++ b/doc/source/internal/helpcenter_training/faq/how_to_compare_the_content_of_a_change_with_the_base_modified_text_images.rst @@ -2,4 +2,6 @@ How to compare the content of a change with the base (modified text/images)? ============================================================================= -Gitea/Github natively support the comparison between the diffs and new PR is nothing else just a diff to a base. Additionally in case of upcoming next commits in existing PR (follow-up updates from Huawei based on QA/UAT reviews) you can see even differences between the commits of the same PR. It means seeing latest changes from Huawei against previous changes in same PR. Images are also shown side by side in case of changes for easy comparison. +Gitea/Github natively support the comparison between the diffs and new PR is nothing else just a diff to a base. Additionally in case of upcoming next commits in existing PR (follow-up updates from Huawei based on QA/UAT reviews) you can see even differences between the commits of the same PR. It means seeing latest changes from Huawei against previous changes in same PR. + +Images are also shown side by side in case of changes for easy comparison. diff --git a/doc/source/internal/helpcenter_training/faq/how_to_request_a_document_modification_for_a_single_comment_or_for_multiple_comments__how_to_notify_huawei_that_we_need_an_update.rst b/doc/source/internal/helpcenter_training/faq/how_to_request_a_document_modification_for_a_single_comment_or_for_multiple_comments__how_to_notify_huawei_that_we_need_an_update.rst index 64ae210..c13bf31 100644 --- a/doc/source/internal/helpcenter_training/faq/how_to_request_a_document_modification_for_a_single_comment_or_for_multiple_comments__how_to_notify_huawei_that_we_need_an_update.rst +++ b/doc/source/internal/helpcenter_training/faq/how_to_request_a_document_modification_for_a_single_comment_or_for_multiple_comments__how_to_notify_huawei_that_we_need_an_update.rst @@ -2,4 +2,10 @@ How to request a document modification (for a single comment or for multiple comments)? How to notify Huawei that we need an update? ==================================================================================================================================== -After finishing the review (and raising the comments) you have 3 options how to close the review: Approve - PR is being approved and can be moved to the next stage Comment - Raising the comments without explicit requirement of any changes (not blocking approval) Request Changes - Approval is not given and PR is blocked by requesting the changes which means that PR should receive another commit of changes and only after that PR will be ready for next review round +After finishing the review (and raising the comments) you have 3 options how to close the review: + + Approve - PR is being approved and can be moved to the next stage + + Comment - Raising the comments without explicit requirement of any changes (not blocking approval) + + Request Changes - Approval is not given and PR is blocked by requesting the changes which means that PR should receive another commit of changes and only after that PR will be ready for next review round diff --git a/doc/source/internal/helpcenter_training/faq/how_will_we_be_notified_once_huawei_will_upload_something_new_doc_or_modify_existing_doc.rst b/doc/source/internal/helpcenter_training/faq/how_will_we_be_notified_once_huawei_will_upload_something_new_doc_or_modify_existing_doc.rst index 59e1507..fec7f0b 100644 --- a/doc/source/internal/helpcenter_training/faq/how_will_we_be_notified_once_huawei_will_upload_something_new_doc_or_modify_existing_doc.rst +++ b/doc/source/internal/helpcenter_training/faq/how_will_we_be_notified_once_huawei_will_upload_something_new_doc_or_modify_existing_doc.rst @@ -2,4 +2,4 @@ How will we be notified once Huawei will upload something (new doc, or modify existing doc)? ============================================================================================ -After Huawei will create new PR in doc-exports respective PR is autocreated in target document repository (for example in https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls) as QA/UAT or other members of the squad are also members of the gitea group which is taking care of the respective service document repositories they should be automatically notified by email about newly created PR in the respective service document repository. +After Huawei will create new PR in doc-exports respective PR is autocreated in target document repository (for example in https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls) as QA/UAT or other members of the squad are also members of the gitea group which is taking care of the respective service document repositories they should be automatically notified by email about newly created PR in the respective service document repository. diff --git a/doc/source/internal/helpcenter_training/faq/what_are_the_exact_locations_where_the_documents_can_be_found_per_each_component.rst b/doc/source/internal/helpcenter_training/faq/what_are_the_exact_locations_where_the_documents_can_be_found_per_each_component.rst index 09f3214..7c7d3e1 100644 --- a/doc/source/internal/helpcenter_training/faq/what_are_the_exact_locations_where_the_documents_can_be_found_per_each_component.rst +++ b/doc/source/internal/helpcenter_training/faq/what_are_the_exact_locations_where_the_documents_can_be_found_per_each_component.rst @@ -2,4 +2,7 @@ What are the exact locations where the documents can be found per each component? ================================================================================= -https://gitea.eco.tsi-dev.otc-service.com/org/docs/teams/docs-orchestration-rw/repositories https://github.com/orgs/opentelekomcloud-docs/teams/docs-orchestration-rw/repositories + + https://gitea.eco.tsi-dev.otc-service.com/org/docs/teams/docs-orchestration-rw/repositories + + https://github.com/orgs/opentelekomcloud-docs/teams/docs-orchestration-rw/repositories diff --git a/doc/source/internal/helpcenter_training/faq/where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues.rst b/doc/source/internal/helpcenter_training/faq/where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues.rst index 1b9bf24..0610e7d 100644 --- a/doc/source/internal/helpcenter_training/faq/where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues.rst +++ b/doc/source/internal/helpcenter_training/faq/where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues.rst @@ -2,4 +2,27 @@ Where and how can I access the system to check all squad components and the current tasks or raised issues? =========================================================================================================== -There are multiple places based on source of the review task. All Gitea links are related to Huawei changes and changes being introduced on the PREPROD docportal: https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/pulls - general place where Huawei is introducing new PRs with the documents imports in HTML file (this is meta repository and not the final repository for a review of the change) https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/pulls - this is place where Huawei's PRs are converted to service RST PRs which are ready for a review by QA/UAT for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls https://gitea.eco.tsi-dev.otc-service.com/org/docs/teams/docs-orchestration-rw/repositories - good starting point for seeing all service doc repositories of the whole squad for PREPROD documentation https://github.com/opentelekomcloud-docs/TARGET-SERVICE-NAME/pulls - this is place where PRs are being created for changes coming from gitea after approval or from external changes (customer/TSI..) for example https://github.com/opentelekomcloud-docs/resource-template-service/pulls https://github.com/orgs/opentelekomcloud-docs/teams/docs-orchestration-rw/repositories - good starting point for seeing all service doc repositories of the whole squad for PROD documentation In future we plan to implement also some monitoring dashboard to have all different PRs under one roof There are multiple places based on source of the issue. All Gitea links are related to issues addressed to Huawei or Ecosystem squad and issues related to PREPROD doc portal https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/issues - general PREPROD docsportal issues https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/issues - this is place for service based issue towards Huawei or Ecosystem squad for PREPROD for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/issues https://github.com/opentelekomcloud-docs/docsportal/issues - general PROD docsportal issues (also customers can raise the issues here) https://github.com/opentelekomcloud-docs/TARGET-SERVICE-NAME/issues - this is place for service based issue towards TSI (also customers can raise issues here) for PROD for example https://github.com/opentelekomcloud-docs/resource-management-service/issues +There are multiple places based on source of the review task. All Gitea links are related to Huawei changes and changes being introduced on the PREPROD docportal: + + https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/pulls - general place where Huawei is introducing new PRs with the documents imports in HTML file (this is meta repository and not the final repository for a review of the change) + + https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/pulls - this is place where Huawei's PRs are converted to service RST PRs which are ready for a review by QA/UAT for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls + + https://gitea.eco.tsi-dev.otc-service.com/org/docs/teams/docs-orchestration-rw/repositories - good starting point for seeing all service doc repositories of the whole squad for PREPROD documentation + + https://github.com/opentelekomcloud-docs/TARGET-SERVICE-NAME/pulls - this is place where PRs are being created for changes coming from gitea after approval or from external changes (customer/TSI..) for example https://github.com/opentelekomcloud-docs/resource-template-service/pulls + + https://github.com/orgs/opentelekomcloud-docs/teams/docs-orchestration-rw/repositories - good starting point for seeing all service doc repositories of the whole squad for PROD documentation + + In future we plan to implement also some monitoring dashboard to have all different PRs under one roof + + +There are multiple places based on source of the issue. All Gitea links are related to issues addressed to Huawei or Ecosystem squad and issues related to PREPROD doc portal + + https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/issues - general PREPROD docsportal issues + + https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/issues - this is place for service based issue towards Huawei or Ecosystem squad for PREPROD for example https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/issues + + https://github.com/opentelekomcloud-docs/docsportal/issues - general PROD docsportal issues (also customers can raise the issues here) + + https://github.com/opentelekomcloud-docs/TARGET-SERVICE-NAME/issues - this is place for service based issue towards TSI (also customers can raise issues here) for PROD for example https://github.com/opentelekomcloud-docs/resource-management-service/issues diff --git a/doc/source/internal/helpcenter_training/faq/where_should_we_check_whether_a_document_related_bug_exists_or_not_for_our_components_if_a_customer_opens_it_or_it_is_coming_from_another_squad.rst b/doc/source/internal/helpcenter_training/faq/where_should_we_check_whether_a_document_related_bug_exists_or_not_for_our_components_if_a_customer_opens_it_or_it_is_coming_from_another_squad.rst index 1ebad04..8bf8da6 100644 --- a/doc/source/internal/helpcenter_training/faq/where_should_we_check_whether_a_document_related_bug_exists_or_not_for_our_components_if_a_customer_opens_it_or_it_is_coming_from_another_squad.rst +++ b/doc/source/internal/helpcenter_training/faq/where_should_we_check_whether_a_document_related_bug_exists_or_not_for_our_components_if_a_customer_opens_it_or_it_is_coming_from_another_squad.rst @@ -2,4 +2,5 @@ Where should we check whether a document related bug exists or not for our components, if a customer opens it or it is coming from another squad? ================================================================================================================================================= -looking at Gitea/Github issues on respective repositories already mentioned in very first questions. Eventually in future we would like to introduce some dashboard for monitoring and visualization such issues based on the service/squad. Q23: +looking at Gitea/Github issues on respective repositories already mentioned in very first questions. Eventually in future we would like to introduce some dashboard for monitoring and visualization such issues based on the service/squad. +Q23: diff --git a/doc/source/internal/helpcenter_training/faq/who_and_how_will_request_a_new_document_update_when_for_instance_a_new_feature_is_planned_to_be_released_for_a_component_in_the_next_delivery_cycle.rst b/doc/source/internal/helpcenter_training/faq/who_and_how_will_request_a_new_document_update_when_for_instance_a_new_feature_is_planned_to_be_released_for_a_component_in_the_next_delivery_cycle.rst index 6443b24..2628123 100644 --- a/doc/source/internal/helpcenter_training/faq/who_and_how_will_request_a_new_document_update_when_for_instance_a_new_feature_is_planned_to_be_released_for_a_component_in_the_next_delivery_cycle.rst +++ b/doc/source/internal/helpcenter_training/faq/who_and_how_will_request_a_new_document_update_when_for_instance_a_new_feature_is_planned_to_be_released_for_a_component_in_the_next_delivery_cycle.rst @@ -2,4 +2,12 @@ Who and how will request a new document update when for instance a new feature is planned to be released for a component in the next delivery cycle? ==================================================================================================================================================== -Again multiple way how to request documentation update: as a part of standard JIRA RM process there's task for Huawei (delivery documentation task) with mandatory field Documentation PR link which Huawei need to fill in with gitea link to be able to close the task. as a new issue in https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/issues as a new issue in https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/issues email contact to Huawei R&D from this link: https://confluence.tsi-dev.otc-service.com/display/HUAW/Documentation+Gitops+Rollout+and+Status+page +Again multiple way how to request documentation update: + + as a part of standard JIRA RM process there's task for Huawei (delivery documentation task) with mandatory field Documentation PR link which Huawei need to fill in with gitea link to be able to close the task. + + as a new issue in https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/issues + + as a new issue in https://gitea.eco.tsi-dev.otc-service.com/docs/TARGET-SERVICE-NAME/issues + + email contact to Huawei R&D from this link: https://confluence.tsi-dev.otc-service.com/display/HUAW/Documentation+Gitops+Rollout+and+Status+page