I would like to add the wiki-rtd migration to the agenda for next tue - and discuss the realities/implications and proposed method of this move after the presentation in today's TSC meeting. Some of the pages slated for migration are still a WIP and/or design pages with open JIRA's and install artifacts in gerrit review.
The proposal to delete wiki pages after the migration is problematic. These are living documents where in some cases the comments/discussion/rework is greater than the page itself. For example the Amazon page specifically brought in AWS and their funding of one of the CD systems. Some of the pages are modified several times a day - I fear that this feedback/review mechanism cannot be replicated on RTD.
Another example - 10 of us have been editing the logging guidelines twice a week with about 30 changes in those 2 hours - doing this directly on read-the-docs would be a lot more difficult without the collaboration ability of wiki.
Another issue is split versions - if we migrate a page for a release and then edit the original or the copy - these changes need to be retrofitted both ways.
Also, we need to ensure that any script/fragment in RTD is actually tested - some is not - we need to follow the same process as normal code reviews in this case - actually run on a system and report results in the gerrit review - then paste commands directly from the console - do not freehand code in RTD.
I raised these issues in several of our doc meetings last year and we still do not really have migration/use plan for the wiki-rtd issues.
Your 10EDT meeting conflicts with the architecture committee meeting - this is mostly why I have not been attending for 3-4 months - I'll attend the next one
2 Comments
Michael O'Brien
Rich Bennett, Gildas Lanilis
I would like to add the wiki-rtd migration to the agenda for next tue - and discuss the realities/implications and proposed method of this move after the presentation in today's TSC meeting. Some of the pages slated for migration are still a WIP and/or design pages with open JIRA's and install artifacts in gerrit review.
ONAP on Kubernetes on Microsoft Azure and the AWS page for example under OOM-822 - Getting issue details... STATUS
The proposal to delete wiki pages after the migration is problematic. These are living documents where in some cases the comments/discussion/rework is greater than the page itself. For example the Amazon page specifically brought in AWS and their funding of one of the CD systems. Some of the pages are modified several times a day - I fear that this feedback/review mechanism cannot be replicated on RTD.
Another example - 10 of us have been editing the logging guidelines twice a week with about 30 changes in those 2 hours - doing this directly on read-the-docs would be a lot more difficult without the collaboration ability of wiki.
Another issue is split versions - if we migrate a page for a release and then edit the original or the copy - these changes need to be retrofitted both ways.
Also, we need to ensure that any script/fragment in RTD is actually tested - some is not - we need to follow the same process as normal code reviews in this case - actually run on a system and report results in the gerrit review - then paste commands directly from the console - do not freehand code in RTD.
I raised these issues in several of our doc meetings last year and we still do not really have migration/use plan for the wiki-rtd issues.
Your 10EDT meeting conflicts with the architecture committee meeting - this is mostly why I have not been attending for 3-4 months - I'll attend the next one
Rich Bennett
Incremental improvement proposed as comments on related JIRA Issue . Please comment improve proposal on DOC-264 - Getting issue details... STATUS