forked from docs/docsportal
add content structure of Helpcenter 3.0 training
Reviewed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com> Co-authored-by: tischrei <tino.schreiber@t-systems.com> Co-committed-by: tischrei <tino.schreiber@t-systems.com>
This commit is contained in:
parent
ed2dcd9e1a
commit
5a2b5b5407
BIN
doc/source/_static/images/added_new_text.png
Executable file
BIN
doc/source/_static/images/added_new_text.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
BIN
doc/source/_static/images/compare_commits.png
Executable file
BIN
doc/source/_static/images/compare_commits.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
BIN
doc/source/_static/images/compare_images.png
Executable file
BIN
doc/source/_static/images/compare_images.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
BIN
doc/source/_static/images/compare_text.png
Executable file
BIN
doc/source/_static/images/compare_text.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
BIN
doc/source/_static/images/helpcenter_gitops.png
Executable file
BIN
doc/source/_static/images/helpcenter_gitops.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
BIN
doc/source/_static/images/jira_document_pr_link.png
Executable file
BIN
doc/source/_static/images/jira_document_pr_link.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
@ -13,3 +13,4 @@ Open Telekom Cloud Service Documentation
|
||||
services
|
||||
developer/index
|
||||
additional/index
|
||||
internal/index
|
||||
|
||||
@ -0,0 +1,51 @@
|
||||
.. _difference_gitea_github:
|
||||
|
||||
=========================
|
||||
Difference Gitea / Github
|
||||
=========================
|
||||
|
||||
Due to the several requirements on Huawei and TSI side 2 gitops stages introduced. At first stage Huawei imports documentation to Gitea and TSI review and approve it.
|
||||
Afterwards documentation change is introduced to Github and TSI formally review it and approve.
|
||||
|
||||
But there are few more differences which are described in the table below:
|
||||
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| **Differences** | **Gitea** | **Github** |
|
||||
+====================================================+====================================================+====================================================+
|
||||
| Link | https://gitea.eco.tsi-dev.otc-service.com/docs | https://github.com/opentelekomcloud-docs/ |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Environment | PREPROD | PROD |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| | internal | public |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Who can introduce changes | Huawei | Anyone (TSI, Huawei, customer) |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Source of documentation | Huawei | TSI+Huawei |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Form of change | Overwrite | Diff |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Portal | https://docs-int.otc-service.com | https://docs.otc.t-systems.com |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Document types | - UMN, API, DEV, other public facing documents | - UMN, API, DEV, other public facing documents |
|
||||
| | | |
|
||||
| | - PD, HLD, CDR, other internal documents | |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
| Stages | 1. Import of the documentation change by Huawei in | 1. Review of the documentation change in target |
|
||||
| | doc-exports repo (html) | document repository |
|
||||
| | | |
|
||||
| | 2. Conversion of the documentation to target | 2. Resolve potential conflicts |
|
||||
| | document repository (rst) | |
|
||||
| | | 3. Approve and gate documentation change in target |
|
||||
| | 3. Review of the documentation change in target | document repository |
|
||||
| | document repository | |
|
||||
| | | |
|
||||
| | 4. Approve and gate documentation change in target | |
|
||||
| | document repository | |
|
||||
| | | |
|
||||
| | 5. Approve and gate documentation change in | |
|
||||
| | doc-exports repo | |
|
||||
| | | |
|
||||
| | 6. Zuul automatically creates documentation change | |
|
||||
| | in Github repo | |
|
||||
+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
|
||||
|
||||
@ -0,0 +1,9 @@
|
||||
=================================================================================================================================
|
||||
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)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 101 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
@ -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 :ref:`very first question <where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues>`.
|
||||
@ -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 :ref:`very first question <where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues>` depending on the affected environment.
|
||||
@ -0,0 +1,17 @@
|
||||
=============================================================================================
|
||||
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.
|
||||
|
||||
**Prerequesits to set the Gate label:**
|
||||
|
||||
1) Confirmity check of Zuul is successful (Zuul approval).
|
||||
2) Approval of Pull Request by Squad member is there.
|
||||
|
||||
If one of these prerequesits is not there. The Zuul pipeline will not start to work and to release the document.
|
||||
|
||||
**How to set the Gate label:**
|
||||
|
||||
.. image:: faq_images/gate_label.png
|
||||
|
||||
@ -0,0 +1,7 @@
|
||||
====================================================================================================================
|
||||
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 :ref:`Previous question <how_can_we_revert_back_to_a_previous_document_version>`. This can be delegated to different person chosen by squad.
|
||||
|
||||
Also please refer for more details in :ref:`general change process flow <documentation_change_process>`.
|
||||
@ -0,0 +1,13 @@
|
||||
.. _how_can_we_revert_back_to_a_previous_document_version:
|
||||
|
||||
======================================================
|
||||
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?
|
||||
==========================================================================
|
||||
|
||||
Requested 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,8 @@
|
||||
================================================================================
|
||||
How does the full document review workflow look like end-to-end on a high level?
|
||||
================================================================================
|
||||
|
||||
The process of the Documentation Change Process under the following link: `https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Process <https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Process>`_ .
|
||||
|
||||
The more detailed description of the QA/UAT document review under the following link: `https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review <https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review>`_ .
|
||||
|
||||
@ -0,0 +1,8 @@
|
||||
======================================================================================================================================
|
||||
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 provide link to Gitea pull request in Huawei Documentation Delivery task in RM:
|
||||
|
||||
.. figure:: /_static/images/jira_document_pr_link.png
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
======================================
|
||||
How to accept a single change/comment?
|
||||
======================================
|
||||
|
||||
By clicking on comments' resolve conversation.
|
||||
@ -0,0 +1,14 @@
|
||||
============================================
|
||||
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
|
||||
|
||||
Adding a comment is a simple thing as described on the following link: `https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review#adding_comments <https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review#adding_comments>`_ .
|
||||
|
||||
Adding a comment for an image is not possible directly as shown on previous link but can be done simply at Conversation tab.
|
||||
|
||||
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,27 @@
|
||||
======================================================================================================
|
||||
How to check the rendered HTML of the entire document in the browser (which button should I click on)?
|
||||
======================================================================================================
|
||||
|
||||
**1) Open the PullRequest (PR) of the prefered document.**
|
||||
|
||||
.. image:: faq_images/html_preview_1.png
|
||||
|
||||
**2) Click on the `Conversation` tab and scroll down.**
|
||||
|
||||
.. image:: faq_images/html_preview_2.png
|
||||
|
||||
**3) Choose the link on `build-otc-<document-type>` or the `Details` link on the Zuul Check-Job.**
|
||||
|
||||
.. image:: faq_images/html_preview_3.png
|
||||
|
||||
**4) The Zuul dashboards opens. Under the `Artifacts` tab the `Docs preview site` can be chosen.**
|
||||
|
||||
.. image:: faq_images/html_preview_4.png
|
||||
|
||||
**5) Sometimes a file structure opens, choose the document type.**
|
||||
|
||||
.. image:: faq_images/html_preview_5.png
|
||||
|
||||
**6) The preview site opens.**
|
||||
|
||||
.. image:: faq_images/html_preview_6.png
|
||||
@ -0,0 +1,21 @@
|
||||
============================================================================
|
||||
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. Text comparison is represented as a "red" (removals) and "green" (addons) highlighted changes as shown on the image below:
|
||||
|
||||
.. figure:: /_static/images/compare_text.png
|
||||
|
||||
Image comparison offers multiple options how to visualize changes. The most common is side by side comparison:
|
||||
|
||||
.. figure:: /_static/images/compare_images.png
|
||||
|
||||
In case there are only added changes or the whole new files are added then the whole file is highlighted by green color:
|
||||
|
||||
.. figure:: /_static/images/added_new_text.png
|
||||
|
||||
|
||||
Gitea/Github also natively support comparison changes between the multiple commits inside of the single pull request. For example follow-up updates from Huawei based on QA/UAT reviews are represented as multiple commits in same PR. The differences between the commits can be seen by clicking on the respecitve commit which will show the differences against the previous commit.
|
||||
|
||||
.. figure:: /_static/images/compare_commits.png
|
||||
|
||||
@ -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,14 @@
|
||||
====================================================================================================================================
|
||||
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
|
||||
|
||||
You can see further details at following link: `https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review#finish_review <https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review#finish_review>`_ .
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
============================================================================================
|
||||
How will we be notified once Huawei will upload something (new doc, or modify existing doc)?
|
||||
============================================================================================
|
||||
|
||||
After Huawei creates new PR in doc-exports repository the respective PR is autocreated in target document repository (for example in https://gitea.eco.tsi-dev.otc-service.com/docs/resource-template-service/pulls). QA/UAT or other squad members are also members of the gitea group with defined ownership of the respective service document repositories and they should be automatically notified by email about newly created PRs.
|
||||
29
doc/source/internal/helpcenter_training/faq/index.rst
Normal file
29
doc/source/internal/helpcenter_training/faq/index.rst
Normal file
@ -0,0 +1,29 @@
|
||||
==========================
|
||||
Frequently Asked Questions
|
||||
==========================
|
||||
|
||||
.. toctree::
|
||||
: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,11 @@
|
||||
=================================================================================
|
||||
What are the exact locations where the documents can be found per each component?
|
||||
=================================================================================
|
||||
|
||||
**PreProd-Environment (Gitea):**
|
||||
|
||||
* https://gitea.eco.tsi-dev.otc-service.com/org/docs/teams/docs-orchestration-rw/repositories
|
||||
|
||||
**Prod-Environment (GitHub):**
|
||||
|
||||
* https://github.com/orgs/opentelekomcloud-docs/teams/docs-orchestration-rw/repositories
|
||||
@ -0,0 +1,33 @@
|
||||
.. _where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues:
|
||||
|
||||
===========================================================================================================
|
||||
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
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
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,6 @@
|
||||
=================================================================================================================================================
|
||||
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 :ref:`very first question <where_and_how_can_i_access_the_system_to_check_all_squad_components_and_the_current_tasks_or_raised_issues>`. 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,8 @@
|
||||
============================================================================
|
||||
Which stages or steps should be performed in Gitea and which ones in GitHub?
|
||||
============================================================================
|
||||
|
||||
Gitea represents PREPROD documentation and eventually internal documentation while Github represents
|
||||
PROD documentation and eventually external documentation (from TSI or customers).
|
||||
|
||||
More comparison details can be found: in :ref:`Differences between Gitea and Github stages <difference_gitea_github>`.
|
||||
@ -0,0 +1,13 @@
|
||||
====================================================================================================================================================
|
||||
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
|
||||
11
doc/source/internal/helpcenter_training/index.rst
Normal file
11
doc/source/internal/helpcenter_training/index.rst
Normal file
@ -0,0 +1,11 @@
|
||||
===================
|
||||
Helpcenter Training
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
introduction
|
||||
workflow
|
||||
difference_gitea_github
|
||||
faq/index
|
||||
44
doc/source/internal/helpcenter_training/introduction.rst
Normal file
44
doc/source/internal/helpcenter_training/introduction.rst
Normal file
@ -0,0 +1,44 @@
|
||||
============
|
||||
Introduction
|
||||
============
|
||||
|
||||
The HelpCenter3.0 is Open Telekom Cloud product developed by Ecosystem squad introducing new approach in the documentation management.
|
||||
It aims to bring the benefits of the gitops approach such as:
|
||||
|
||||
- Openness
|
||||
- Transparency
|
||||
- Comprehensive review capabilities
|
||||
- Full control during the documentation lifecycle
|
||||
- Documentation as a source code
|
||||
|
||||
.. figure:: /_static/images/helpcenter_gitops.png
|
||||
|
||||
Solution is completely open source based and HLD is described at https://docs.otc-service.com/system-config/docsportal.html
|
||||
Implementation is based on:
|
||||
|
||||
- Restructured Text (RST) as source documentation format
|
||||
- Gitea/Github as a repository
|
||||
- Zuul as a CI/CD engine for workflows
|
||||
- Sphinx as a documentation rendering framework (HTML/PDF/...
|
||||
- OpenSearch as a search engine
|
||||
- Swift object storage as a storage for documentation
|
||||
- Pandoc as a documentation converter
|
||||
- OTC Infrastructure (ECS, CCE, ELB, ...)
|
||||
|
||||
HC3.0 comes with the following features:
|
||||
|
||||
- Support of UMN, API, DEV and other public facing documents
|
||||
- PROD and PREPROD documentation portal:
|
||||
|
||||
- docs.otc.t-systems.com
|
||||
- docs-int.otc.service.com
|
||||
|
||||
- Support of all old HC links redirections
|
||||
- Search functionality
|
||||
- Mobile-ready UI layout
|
||||
- Report issue functionality directly on any page
|
||||
- Suggest documentation fix functionality
|
||||
- Consolidation of extra content like blueprints, tools, and libraries for developers
|
||||
- One repository represents one cloud service
|
||||
- Each squad can control and manage their documentation independently
|
||||
- Automatization and check jobs across whole documentation lifecycle (from import to release)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 478 KiB |
File diff suppressed because one or more lines are too long
49
doc/source/internal/helpcenter_training/workflow.rst
Normal file
49
doc/source/internal/helpcenter_training/workflow.rst
Normal file
@ -0,0 +1,49 @@
|
||||
.. _documentation_change_process:
|
||||
|
||||
Documentation Change Process
|
||||
============================
|
||||
|
||||
The following figure provides an overview about the current helpcenter 3.0 process.
|
||||
|
||||
|
||||
.. image:: training_images/helpcenter_3.0_process.drawio.png
|
||||
:target: training_images/helpcenter_3.0_process.drawio.png
|
||||
:alt: helpcenter_3.0_process
|
||||
|
||||
|
||||
Document Change Process Description
|
||||
-----------------------------------
|
||||
|
||||
**Huawei Documentation System**
|
||||
|
||||
1) Huawei employee / Squad member receives Jira task to deliver new documentation from Huawei documentation system of specific service.
|
||||
2) The documentation files are exported in HTML format and needs to be converted to RST sources which will be used by Sphinx rendering engine in a later step.
|
||||
|
||||
**PreProduction Environment (Gitea)**
|
||||
|
||||
3) Huawei employee / Squad member creates a fork from ``doc-exports`` repository. The new documentation needs to be pushed into the forked ``doc-exports`` repository. A detailed description can be found under the following link: `"How to fork a repository in Gitea and push changes." <https://gitea.eco.tsi-dev.otc-service.com/docs/doc-exports/wiki/Huawei-instructions-to-propose-changes>`_.
|
||||
4) After the forked ``doc-exports`` repository has been updated, a Pull Request to the original / upstream ``doc-exports`` repository needs to be opened.
|
||||
5) The automation pipeline tool Zuul CI/CD converts the delivered HTML files to reStructuredText (RST) sources with a self-written script.
|
||||
6) These RST source files will be stored in single repositories located in Gitea, too. For this purpose, Zuul opens a Pull Request in the specific service repository, e.g. ``UMN`` (user manual) documentation for service ``CSS``. In the open Pull Request users are able to see differences between the old state of the documentation and the new one. Gitea provides suitable tools to comment specific lines of code, to approve a Pull Request or request changes.
|
||||
7) Additionally, another pipeline in Zuul builds a preview documentation from the RST files included in the Pull Request which can be used in the review process. `Click on this reference to see how to open Pre-rendered documentation after opening an Pull Request. <https://gitea.eco.tsi-dev.otc-service.com/docs/docsportal/wiki/Review#pre_rendered_doc>`_
|
||||
8) Assigned squad member(s) start the review process of the auto-created Pull Request and communicate their feedback. This can be done via the included functionality of Gitea to provide comments to a specific line of code.
|
||||
9) If the Pull Request fullfils all expectations, the Pull Request will be approved by the reviewer via ``Approve`` selection and the steps 10 and 11 can be skipped. The Pull Request is marked as ``approved``.
|
||||
10) The Pull Request does not fullfil all expectations and review comments needs to be added to the specific lines of code in the target repository of the specific service. After all comments are placed, the review of the Pull Request must be finished with ``Request changes`` selection instead of ``Approve``.
|
||||
11) Huawei collects comments and prepare new documentation change or reply to the comments. There are two possible options to go further:
|
||||
|
||||
a. Huawei member uses the comments to prepare a new documentation delivery from the beginning (out of Huawei documentation system). The whole process starts from the beginning.
|
||||
b. Changes are made directly in the Pull Request. The changes are tracked by the Huawei employee and changed in the Huawei documentation system afterwards.
|
||||
|
||||
12) After the review has been approved, the Squads product owner or a privileged squad member can add the ``gate`` label to the Pull Request.
|
||||
13) The ``gate`` label triggers another CI/CD pipeline of Zuul to render the final PreProd documentation on https://docs-int.otc-service.com/.
|
||||
|
||||
**Production Environment (GitHub)**
|
||||
|
||||
14) Additionally, Zuul opens a Pull Request in GitHub in the specific service repository to update the Production documentation, too.
|
||||
15) If there are merge conflicts, these needs to be solved (16). If no conflicts occure, skip to 17.
|
||||
16) The review squad member must decide how to fix the conflict and what content is supposed to be changed. A discussion is necessary with the Product Owner if further judgement is needed.
|
||||
17) If no merge conflicts are present, Zuul renders a preview documentation and store it to Swift object storage.
|
||||
18) A member conduct a formal review of the documentation changes.
|
||||
19) The Pull Request will be approved by the member.
|
||||
20) After the review has been approved, the Squads product owner or a privileged squad member can add the ``gate`` label to the Pull Request.
|
||||
21) Zuul builds and releases the final documentation on production environment: https://docs.otc.t-systems.com/
|
||||
8
doc/source/internal/index.rst
Normal file
8
doc/source/internal/index.rst
Normal file
@ -0,0 +1,8 @@
|
||||
======================
|
||||
Internal Documentation
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
helpcenter_training/index
|
||||
Loading…
x
Reference in New Issue
Block a user