forked from docs/docsportal
Adding Q&A files
This commit is contained in:
parent
9499ed98b3
commit
bf4f4530be
@ -0,0 +1,5 @@
|
|||||||
|
=================================================================================================================================
|
||||||
|
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)
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
======================================================================================================================
|
||||||
|
How and where should we submit bugs when a non-conformity is found in an already released/deployed PROD documentation?
|
||||||
|
======================================================================================================================
|
||||||
|
|
||||||
|
Using Gitea/Github issues on respective repositories already mentioned in very first questions.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
==================================================================================================
|
||||||
|
How and where should we submit bugs when the documentation URL is wrong (the link is not working)?
|
||||||
|
==================================================================================================
|
||||||
|
|
||||||
|
Using Gitea/Github issues on respective repositories already mentioned in very first questions depending on the affected environment.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
=============================================================================================
|
||||||
|
How can the docs be deployed to PRE-PROD and PROD and who will be the responsible to do that?
|
||||||
|
=============================================================================================
|
||||||
|
|
||||||
|
By triggering the label "gate" on gitea/github the respective automated jobs will trigger final merge and build of the documentation as well as publishing of the documentation to respective portal (PREPROD/PROD). Responsibility can be addressed to the labelling permission. Remaining stuff is in hands of zuul automation.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
====================================================================================================================
|
||||||
|
How can we accept the entire document when we are fine with it? Who will have the right to make a doc version final?
|
||||||
|
====================================================================================================================
|
||||||
|
|
||||||
|
See the last option in previous comment. This can be delegated to different persion chosen by squad.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
======================================================
|
||||||
|
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.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
==========================================================================
|
||||||
|
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.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
=================================================================================================================
|
||||||
|
How does document versioning work during the document updates? How will the final accepted document be versioned?
|
||||||
|
=================================================================================================================
|
||||||
|
|
||||||
|
One document version can be understood as one documentation PR. Even if in PR there are mutliple commits based on several review iterations at the ends those commits are squashed to a single change and presented as one change in gitea/github. Of course in case of valid reasons Huawei might introduce more version updates directly in change history chapter.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
================================================================================
|
||||||
|
How does the full document review workflow look like end-to-end on a high level?
|
||||||
|
================================================================================
|
||||||
|
|
||||||
|
link to process
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
======================================================================================================================================
|
||||||
|
How the document traceability to DMs/RMs in JIRA will work, who will be the responsible to place the links in the related JIRA ticket?
|
||||||
|
======================================================================================================================================
|
||||||
|
|
||||||
|
Huawei is responsible to do that in Huawei Documentation Delivery task in RM
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
======================================
|
||||||
|
How to accept a single change/comment?
|
||||||
|
======================================
|
||||||
|
|
||||||
|
By clicking on comments' resolve conversation.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
============================================
|
||||||
|
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.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
======================================================================================================
|
||||||
|
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
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
=============================================================================
|
||||||
|
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.
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
==========================
|
||||||
|
How to reply to a comment?
|
||||||
|
==========================
|
||||||
|
|
||||||
|
Natively supported by Gitea/Github by clicking on comments options and choosing quote reply
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
====================================================================================================================================
|
||||||
|
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
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
============================================================================================
|
||||||
|
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.
|
||||||
@ -5,3 +5,25 @@ Frequently Asked Questions
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
|
how_do_we_deal_with_open_tickets_may_we_have_a_separate_session_for_that
|
||||||
|
where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues
|
||||||
|
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
|
||||||
|
how_does_the_full_document_review_workflow_look_like_end-to-end_on_a_high_level
|
||||||
|
which_stages_or_steps_should_be_performed_in_gitea_and_which_ones_in_github
|
||||||
|
what_are_the_exact_locations_where_the_documents_can_be_found_per_each_component
|
||||||
|
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
|
||||||
|
how_will_we_be_notified_once_huawei_will_upload_something_new_doc_or_modify_existing_doc
|
||||||
|
how_the_document_traceability_to_dms_rms_in_jira_will_work_who_will_be_the_responsible_to_place_the_links_in_the_related_jira_ticket
|
||||||
|
how_to_check_the_rendered_html_of_the_entire_document_in_the_browser_which_button_should_i_click_on
|
||||||
|
how_to_compare_the_content_of_a_change_with_the_base_modified_text_images
|
||||||
|
how_to_add_a_comment_for_a_text_or_an_image
|
||||||
|
how_to_reply_to_a_comment
|
||||||
|
how_to_accept_a_single_change_comment
|
||||||
|
how_to_request_a_document_modification_for_a_single_comment_or_for_multiple_comments__how_to_notify_huawei_that_we_need_an_update
|
||||||
|
how_does_document_versioning_work_during_the_document_updates_how_will_the_final_accepted_document_be_versioned
|
||||||
|
how_can_we_revert_back_to_a_previous_document_version
|
||||||
|
how_can_we_accept_the_entire_document_when_we_are_fine_with_it_who_will_have_the_right_to_make_a_doc_version_final
|
||||||
|
how_can_the_docs_be_deployed_to_pre-prod_and_prod_and_who_will_be_the_responsible_to_do_that
|
||||||
|
how_and_where_should_we_submit_bugs_when_a_non-conformity_is_found_in_an_already_released_deployed_prod_documentation
|
||||||
|
how_and_where_should_we_submit_bugs_when_the_documentation_url_is_wrong_the_link_is_not_working
|
||||||
|
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
|
||||||
|
|||||||
@ -0,0 +1,5 @@
|
|||||||
|
=================================================================================
|
||||||
|
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
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
===========================================================================================================
|
||||||
|
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
|
||||||
@ -0,0 +1,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:
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
============================================================================
|
||||||
|
Which stages or steps should be performed in Gitea and which ones in GitHub?
|
||||||
|
============================================================================
|
||||||
|
|
||||||
|
XXX
|
||||||
@ -0,0 +1,5 @@
|
|||||||
|
====================================================================================================================================================
|
||||||
|
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
|
||||||
Loading…
x
Reference in New Issue
Block a user