TABLE OF CONTENTS
DeveloperWiki and ReadTheDocs Usage Policy
The TSC Vote (2020, Feb. 19) approved the folowing Wiki/RTD usage policy:
DEVELOPER WIKI: for ONAP release, project, subcommitee and development related content, e.g.
- project management (meetings, plans, milestones, members, ...)
- project specific development guides
- ongoing activities and discussions
- ONAP community event documentation
READ THE DOCS: for all formal ONAP E2E and component documentation, e.g.
- ONAP overview, architecture, API
- ONAP developer guides (e.g. Documentation guide)
- ONAP user guides (E2E)
- ONAP component guides, release notes
- ONAP administration/operations guides
- ONAP use-case description and usage
- ONAP tutorials
- ONAP release notes
For details on how to contribute to the formal ONAP documentation, refer to the ONAP Documentation Guide.
Accordingly, already available "formal ONAP E2E and component documentation" in the Developer Wiki will be migrated to ReadTheDocs (in case the information is still valid).
DeveloperWiki Content
Some outlook and history for migrations.
To be evaluated
- Architecture
- Developing ONAP
- Setting up ONAP
- Integrating with ONAP
- Supporting Tools
plus all other active projects (priority not set yet)
Currently under evaluation
- none
Already evaluated/migrated
Archived in the Confluence space Deprecated under Migrated or Deprecated Documentation Policy:
Related Jira Entries
DOC-590 - Getting issue details... STATUS
DOC-435 - Getting issue details... STATUS
DOC-443 - Getting issue details... STATUS
DOC-450 - Getting issue details... STATUS
DOC-506 - Getting issue details... STATUS
DOC-591 - Getting issue details... STATUS
The Process of Migration
Follow the described steps if you need to migrate DeveloperWiki content to ReadTheDocs:
01. Read the "DeveloperWiki and ReadTheDocs Usage Policy"
- To understand the reason behind this migration task and to know what DeveloperWiki content we are targeting it is essential to read and understand the TSC approved policy.
02. Identify formal ONAP documentation content in the DeveloperWiki
- Identify formal ONAP documentation content in the DeveloperWiki which has to be migrated to ReadTheDocs in accordance to the above policy.
- Ensure that the content is up-to-date and describes the functionality of the latest ONAP release. If not, please update documentation accordingly.
- In case of deprecated content, continue with the step Label the DeveloperWiki page(s) as "Migrated to ReadTheDocs" or "Deprecated Content"
03. Label the DeveloperWiki page(s) to show the "Migration to ReadTheDocs in Progress"
- On top of the page please add the following label. Add the correct date and your name.
- Example for a "Migration in Progress"
Migration to ReadTheDocs in Progress
Further updates must be done in the corresponding RST file(s) by following the build process for documentation.
25.04.2019, Your.Name
04. Update the Migration Tracking Information
- Add/change information about what content is currently migrated (page title) and who does it (your name). For this, edit this page at section "DeveloperWiki Content - To be evaluated / Currently under evaluation".
- Create a Jira ticket for this activity and add it to the list of "Related Jira Entries" on this page.
05. Export DeveloperWiki page(s)
- Depending on the type and number of Confluence macros used to design the page, the quality of the export will vary. "Simple" Confluence pages with no macros allow much better results than pages which are using e.g. the "Deck of Cards" macro (see example) or others.
- Workaround: Copy the needed content to a new "Blanc Page" without using problematic macros and export it instead of the original page.
- The script "c2m.sh" automates the export of (multiple) pages. See DOC Tools page for a description of available tools, capabilities and limitations.
06. Prepare Content for usage in ReadTheDocs
- Check and correct the export results (restructuredText).
07. Contribute to the ONAP Master Branch
- For details on how to contribute to the formal ONAP documentation, refer to the ONAP Documentation Guide.
08. Label the DeveloperWiki page(s) as "Migrated to ReadTheDocs" or "Deprecated Content"
- On top of the page please add one of the following labels. Add the correct date and your name.
- Example for "Migrated Content"
Migrated to ReadTheDocs
Further updates must be done in the corresponding RST file(s) by following the build process for documentation.
25.04.2019, Your.Name
- Example for "Deprecated Content"
Deprecated Content
25.04.2019, Your.Name
09. Archive the DeveloperWiki page(s)
- Migrated (or deprecated) content must be moved from the Confluence space "Developer Wiki" to the Confluence space "Deprecated".
- To archive the migrated/deprecated DeveloperWiki page, go to the top of page, open the page menu "[...]" on the right side and choose the "Move" command. Move the page below "Migrated or Deprecated Documentation Policy".
10. Update the Migration Tracking Information
- Remove the provided migration information on this page. For this, edit the section "DeveloperWiki Content - Currently under evaluation".
- Information at "DeveloperWiki Content - Already evaluated/migrated" is updated automatically after you have archived the migrated DeveloperWiki page(s) as described.
- Close the Jira ticket.