eclipse-platform
Wiki migration for the platform/platform UI
Eclipse foundation shutdowns Wiki on eclipse org and we have to
- decide where wiki should be hosted for platform.
- migrate "useful" pages to the "right" new home.
There are few pages that probably worth to be migrated (briefly looked over categories):
- https://wiki.eclipse.org/Evolving_Java-based_APIs + follow up pages are must have
- https://wiki.eclipse.org/Version_Numbering must have
- https://wiki.eclipse.org/Category:Platform_UI
- https://wiki.eclipse.org/Category:API
- https://wiki.eclipse.org/Team
- https://wiki.eclipse.org/Category:RCP
- https://wiki.eclipse.org/Category:UI_Guidelines
- https://wiki.eclipse.org/Category:Data_Binding
- https://wiki.eclipse.org/Category:E4
- https://wiki.eclipse.org/Category:Best_Practices (not sure if this is a subset or superset of https://github.com/eclipse-platform/ui-best-practices)
- ...
- Few others not listed under any category...
Note: we have already few (migrated) wikis under:
- https://github.com/eclipse-platform/.github/wiki (not sure if that should be the "main one"?). See also discussion on https://github.com/eclipse-platform/eclipse.platform.releng/discussions/216
- https://github.com/eclipse-platform/eclipse.platform.swt/wiki (originally migrated from https://wiki.eclipse.org/SWT by @trancexpress)
- https://github.com/eclipse-platform/eclipse.platform.releng.aggregator/wiki (originally migrated from https://wiki.eclipse.org/Category:Eclipse_Platform_Releng by @trancexpress and moved by me today from https://github.com/eclipse-platform/eclipse.platform.releng/wiki, following the repo merge)
@iloveeclipse I don't think the IDE WG should be involved in the decision here. Where we put the documentation is a project decision and sponsoring wouldn't help in taking the decision. Once we have agreed on where to deploy stuff, then we can document a migration plan and maybe ask sponsoring some someone can focus on rolling out the plan.
In general, I think everything generic for all components should get to the "main" documentation area ( https://github.com/eclipse-platform/.github/wiki apparently so far); other more specific pages (eg Data Binding) should move to the documentation of the repo they are most related to (eg eclipse.platform.ui), just like it was partly done for SWT and Releng stuff. So I would say to just continue as it's already been done so far.
(as usual, I want to use this opportunity to discourage usage of wiki in general, and instead recommend usage of a "DEVELOPER_DOCS" or "CONTRIBUTING" folder inside the same repo in general, as it allows better tracking of contributions, with review capabilities, authors tracking to treat documentation contributors just as well as code contributors in the history, and makes the documentation easy to get offline to anyone who could fork the repo)
Yes, for the SimRel wiki page migration, @jonahgraham also concluded that github wikis were not a good plan. And yes, the project should make the decisions and the plan. Who does the work or helps with the work is a separate concern that comes after the decisions and plans.
I don't think the IDE WG should be involved in the decision here. Where we put the documentation is a project decision and sponsoring wouldn't help in taking the decision.
I less care about "where" but about "who".
The question was also if IDE WG can take over migration for platform and if @jonahgraham could check that.
Last time Simeon did that (sponsored by Advantest) we needed lot of extra work after "automated" conversion to fix cross linking, formatting etc.
The Planning Council can add it to the prioritized dev efforts - I think the planning council is likely to approve that. But it still leaves the concrete issue of who unresolved, someone needs to take on that work, so if you know someone who would want to do it, please be in touch.
I'll add this to the agenda for the next Planning Council call on Wednesday 1 Nov.
egit has used some automation to convert the wiki content to GitHub markdown: https://github.com/msohn/EclipseWikiCrawler, maybe that would be useful for others too. In the case of egit, I'm currently promoting the idea of a further conversion to AsciiDoc, because that allows better generation workflows than the GitHub wiki content, IMO: https://github.com/eclipse-egit/egit/issues/6
Thanks @Bananeweizen I have a look at the EGit tooling
IIRC I wanted to use adoc in the past for the README.md (currently) but at this point this was refused. For now I stay with Markdown, in my opinion it does not make sense to use different markdown languages. If the PMC decides that we should Asciidoc I'm in favor of this, our website vogella.com uses also Asciidoc and I personally prefer this.
I found that user doc is best migrated to the eclipse help (what might wants to support having adoc as a source) because it is automatically available as web page on each release. Thinks like Version_Numbering might better get to the contribution guide or some central place (committer handbook?) if the apply to eclipse at large.
I found that user doc is best migrated to the eclipse help (what might wants to support having adoc as a source) because it is automatically available as web page on each release. Thinks like Version_Numbering might better get to the contribution guide or some central place (committer handbook?) if the apply to eclipse at large.
Ask three guys and get three different answers. :-) I suggested a while to migrate at least the N&N to Asciidoc or Markdown and this was blocked for a while (with the reason that the team needed more time to evaluate this potential change) and not executed yet. IMHO this would be most logical point to start, as it is the only document which is regulary updated.
From https://wiki.eclipse.org/Category:Platform_UI I think worth migration are:
- https://wiki.eclipse.org/JFace
- https://wiki.eclipse.org/JFaceSnippets
- https://wiki.eclipse.org/Platform_UI/Accessibility_Features
- https://wiki.eclipse.org/Platform_UI/Performance_Tests (this is most likely complete outdated but AFAICS one of the few sources of information about the performance tests)
This also looks value, but I suggest to move these to ONE page, instead of create a page per existing wiki
- https://wiki.eclipse.org/JFace_Data_Binding
- https://wiki.eclipse.org/JFace_Data_Binding_Introduction
- https://wiki.eclipse.org/JFace_Data_Binding/Getting_started
- https://wiki.eclipse.org/JFace_Data_Binding/Snippets
- https://wiki.eclipse.org/JFace_Data_Binding/Observable
- https://wiki.eclipse.org/JFace_Data_Binding/Binding
- https://wiki.eclipse.org/JFace_Data_Binding/Data_Binding_Context
- https://wiki.eclipse.org/JFace_Data_Binding/Converter
- https://wiki.eclipse.org/JFace_Data_Binding/Validators
- https://wiki.eclipse.org/JFace_Data_Binding/Realm
- https://wiki.eclipse.org/JFace_Data_Binding/TrackedGetter
- https://wiki.eclipse.org/JFace_Data_Binding/Master_Detail
Anyone aware of more wiki pages in the https://wiki.eclipse.org/Category:Platform_UI category which should survive? The rest of the pages are IMHO obsolete like the "How to contribute" or the command section wtih its planned developments for the action sets.
https://github.com/eclipse-platform/eclipse.platform/pull/1130 - Fixes Link to Architecture concil https://github.com/eclipse-platform/eclipse.platform/pull/1131 - Export-Package migrated
From the https://wiki.eclipse.org/Team I think it is worth migrating the following pages:
- https://wiki.eclipse.org/Team_FAQ
- https://wiki.eclipse.org/Compare_Word_Documents
The rest of the documents seem outdated and not relevant. Let me know if you think other documents in the team category should also be migrated.
From the https://wiki.eclipse.org/Category:RCP I think it is worth migrating the following pages:
- https://wiki.eclipse.org/Eclipse_Plug-in_Development_FAQ
- https://wiki.eclipse.org/JFaceSnippets
- https://wiki.eclipse.org/Rich_Client_Platform
- https://wiki.eclipse.org/Rich_Client_Platform/Book
- https://wiki.eclipse.org/Rich_Client_Platform/FAQ
- https://wiki.eclipse.org/Rich_Client_Platform/How-to
Let me know if you think other documents in this category should also be migrated.
From the https://wiki.eclipse.org/Category:Data_Binding I think it is worth migrating the following pages:
- https://wiki.eclipse.org/JFace_Data_Binding
- https://wiki.eclipse.org/JFace_Data_Binding_Introduction
- https://wiki.eclipse.org/JFace_Data_Binding/Binding
- https://wiki.eclipse.org/JFace_Data_Binding/Conformance_Tests
- https://wiki.eclipse.org/JFace_Data_Binding/FAQ
- https://wiki.eclipse.org/JFace_Data_Binding/Observable
- https://wiki.eclipse.org/JFace_Data_Binding/Realm
- https://wiki.eclipse.org/JFace_Data_Binding/Snippets
From https://wiki.eclipse.org/Category:Best_Practices I think it is worth migrating the following pages:
https://wiki.eclipse.org/Evolving_Java-based_APIs https://wiki.eclipse.org/Progress_Reporting https://wiki.eclipse.org/Status_Handling_Best_Practices https://wiki.eclipse.org/Version_Numbering
Let me know if you think other documents in this category should also be migrated.
The following pages have been migrated:
https://wiki.eclipse.org/Platform_UI/Accessibility_Features https://wiki.eclipse.org/Command_Core_Expressions https://wiki.eclipse.org/Common_Navigator_Framework https://wiki.eclipse.org/Common_Navigator_Framework_Use_Cases https://wiki.eclipse.org/Eclipse4/RCP/Dependency_Injection https://wiki.eclipse.org/Eclipse4/RCP/Contexts https://wiki.eclipse.org/Eclipse4/RCP/EAS/List_of_All_Provided_Services https://wiki.eclipse.org/Eclipse4/RCP/Event_Model https://wiki.eclipse.org/E4/Event_Processing https://wiki.eclipse.org/Eclipse4/RCP/FAQ https://wiki.eclipse.org/Eclipse_Plug-in_Development_FAQ https://wiki.eclipse.org/Eclipse_Corner https://wiki.eclipse.org/JFace https://wiki.eclipse.org/JFace_Data_Binding https://wiki.eclipse.org/JFace_Data_Binding_Introduction https://wiki.eclipse.org/JFace_Data_Binding/Getting_started https://wiki.eclipse.org/JFace_Data_Binding/Snippets https://wiki.eclipse.org/JFace_Data_Binding/Observable https://wiki.eclipse.org/JFace_Data_Binding/Binding https://wiki.eclipse.org/JFace_Data_Binding/Data_Binding_Context https://wiki.eclipse.org/JFace_Data_Binding/Converter https://wiki.eclipse.org/JFace_Data_Binding/Validators https://wiki.eclipse.org/JFace_Data_Binding/Realm https://wiki.eclipse.org/JFace_Data_Binding/TrackedGetter https://wiki.eclipse.org/JFace_Data_Binding/Master_Detail https://wiki.eclipse.org/JFace_Data_Binding/Conformance_Tests https://wiki.eclipse.org/JFace_Data_Binding/Runtime_Dependencies https://wiki.eclipse.org/JFace_Data_Binding/FAQ https://wiki.eclipse.org/JFaceSnippets https://wiki.eclipse.org/Platform_Command_Framework https://wiki.eclipse.org/Platform_Expression_Framework https://wiki.eclipse.org/Rich_Client_Platform https://wiki.eclipse.org/Rich_Client_Platform/FAQ https://wiki.eclipse.org/Rich_Client_Platform/How-to https://wiki.eclipse.org/Rich_Client_Platform/Book https://wiki.eclipse.org/E4/CSS https://wiki.eclipse.org/E4/CSS/SWT_Mapping https://wiki.eclipse.org/E4/CSS/Add_Selector https://wiki.eclipse.org/E4/CSS/Add_Styleable_Property https://wiki.eclipse.org/Evolving_Java-based_APIs https://wiki.eclipse.org/Version_Numbering https://wiki.eclipse.org/Evolving_Java-based_APIs_II https://wiki.eclipse.org/Evolving_Java-based_APIs_III https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process https://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy https://wiki.eclipse.org/Progress_Reporting https://wiki.eclipse.org/Status_Handling_Best_Practices https://wiki.eclipse.org/Export-Package https://wiki.eclipse.org/Provisional_API_Guidelines https://wiki.eclipse.org/Naming_Conventions https://wiki.eclipse.org/PDE/API_Tools/User_Guide https://wiki.eclipse.org/PDE/API_Tools/Resources https://wiki.eclipse.org/PDE/API_Tools/Use_Cases https://wiki.eclipse.org/Adaptor_Hooks
Links in the documents have been upgraded / updated and also partially the content of the documents. The wiki pages have been updated with a header pointing to the new location so hopeful Google and co will soon starting showing results for the new pages.
Any other platform / platform.ui documents which you are aware that should be migrated away from the wiki?
Any other platform / platform.ui documents which you are aware that should be migrated away from the wiki?
These pages look relevant to move:
- [ ] https://wiki.eclipse.org/Eclipse_Project_Update_Sites (slightly out of date page - this may just need a warning header to where to find that information today)
- [ ] https://wiki.eclipse.org/The_Official_Eclipse_FAQs (has this been moved somewhere yet - it is lots and lots of sub pages)
- [ ] https://wiki.eclipse.org/Eclipse/API_Central (most of the content/links have been migrated, but this is the entry point for Eclipse API docs so could use a link to a new entry point)
The following pages could use a review to see if they should be migrated, or a banner added to them:
- [ ] https://wiki.eclipse.org/Platform_UI_Command_Design
- [ ] https://wiki.eclipse.org/Platform_UI_Error_Handling
- [ ] https://wiki.eclipse.org/Menu_Contributions
- [ ] https://wiki.eclipse.org/How_to_add_things_to_the_Eclipse_doc
- [ ] https://wiki.eclipse.org/Rich_Client_Platform/Text_Editor_Examples
- [ ] https://wiki.eclipse.org/Managing_Multiple_Instances_of_a_View
- [ ] https://wiki.eclipse.org/UI_Checklist
- [ ] https://wiki.eclipse.org/UI_Forms
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Common_Elements
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Consistency
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Style
- [ ] https://wiki.eclipse.org/UI_Guidelines/Preferences
- [ ] https://wiki.eclipse.org/Talk:User_Interface_Guidelines
- [ ] https://wiki.eclipse.org/Internationalization
- [ ] https://wiki.eclipse.org/Eclipse_Doc_Style_Guide
These pages look relevant to move:
- [ ] https://wiki.eclipse.org/Eclipse_Project_Update_Sites (slightly out of date page - this may just need a warning header to where to find that information today)
- [ ] https://wiki.eclipse.org/The_Official_Eclipse_FAQs (has this been moved somewhere yet - it is lots and lots of sub pages)
- [ ] https://wiki.eclipse.org/Eclipse/API_Central (most of the content/links have been migrated, but this is the entry point for Eclipse API docs so could use a link to a new entry point)
I look into these.
The following pages could use a review to see if they should be migrated, or a banner added to them:
- [ ] https://wiki.eclipse.org/Platform_UI_Command_Design
- [ ] https://wiki.eclipse.org/Platform_UI_Error_Handling
- [ ] https://wiki.eclipse.org/Menu_Contributions
- [ ] https://wiki.eclipse.org/How_to_add_things_to_the_Eclipse_doc
- [ ] https://wiki.eclipse.org/Rich_Client_Platform/Text_Editor_Examples
- [ ] https://wiki.eclipse.org/Managing_Multiple_Instances_of_a_View
- [ ] https://wiki.eclipse.org/UI_Checklist
- [ ] https://wiki.eclipse.org/UI_Forms
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Common_Elements
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Consistency
- [ ] https://wiki.eclipse.org/UI_Graphics_:Design:_Style
- [ ] https://wiki.eclipse.org/UI_Guidelines/Preferences
- [ ] https://wiki.eclipse.org/Talk:User_Interface_Guidelines
- [ ] https://wiki.eclipse.org/Internationalization
- [ ] https://wiki.eclipse.org/Eclipse_Doc_Style_Guide
Most of these I already reviewed and found them not relevant for migration. I redo them and will add a comment if I think they are not worth migrating or already covered (better) by the UI guideline page.
The official Eclipse FAQ had ~370 sub-pages. That was an unexpected number of wiki pages for the migration. PR is here https://github.com/eclipse-platform/eclipse.platform/pull/1199/
The rest of your list @jonahgraham have also been migrated, except the UX pages, which are already covered by the UX guidelines, we added links in the corresponding wiki pages.
Thanks @vogella - I have cc'ed you an email off list on this topic too.