🔮[RFC]: OpenIM WebSite Platform Enhancements

[cubxxw]

中文设计稿

I have designed the key modules for OpenIM:

• Blog: OpenIM's official blog, showcasing the latest posts and handpicked articles.
• Docs: Comprehensive documentation for the OpenIM ecosystem.
• Community: The vibrant community ecosystem of OpenIM, including biweekly meetings, affiliate events, and face-to-face interactions.

Critical Design Details

With a vision for long-term sustainability and community engagement, I hold the OpenIM site's design to the highest standards:

1. User Interface (UI):
   • Color Scheme: Deep blue is chosen as the primary hue, signifying technology and reliability, complemented by shades of grey or white for a clean and professional aesthetic.
   • Responsive Design: Optimized for various screen sizes, ensuring a consistent user experience across desktops, tablets, and mobile devices.
   • User Navigation: A clear top navigation bar showcasing the three main modules: “Blog,” “Docs,” and “Community,” enabling swift user access.
2. Blog Module:
   • Featured Posts: The homepage or main blog page prominently displays the newest and curated articles to engage visitors.
   • Categories and Tags: Facilitates content discovery based on user interests or themes.
   • Comment Functionality: Users can provide feedback and engage in discussions beneath each post.
3. Docs Module:
   • Layered Structure: Documentation is categorized into levels like "Beginner," "Advanced," and "API Reference," catering to users of varying expertise.
   • Search Capability: Empowers users to swiftly locate pertinent documentation.
   • Version Control: As OpenIM evolves, its documentation incorporates version management for users to find relevant document editions.
4. Community Module:
   • Event Calendar: Provides insights into upcoming biweekly meetings, offline interactions, and other event details.
   • Member Showcase: Highlights active community participants or contributors to foster greater involvement.
   • Resource Links: Curates links to tools, plugins, and other resources pertinent to OpenIM.
5. Other Considerations:
   • Multilingual Support: Given OpenIM's potential global reach, offering multiple languages broadens its audience scope.
   • Access Speed: A commitment to swift website loading times using technologies like CDN and code optimization.
   • Security: Ensuring protection against malicious attacks or misuse by employing HTTPS and periodic security reviews.

Documentation Automation & Synchronization Strategy

Document Segmentation & Design

For consolidating vast projects, managing and organizing documents is paramount. By segmenting the content, we effectively cater to diverse reader profiles:

• Document Abstraction Layers:

  Significant design efforts ensure each section serves a distinct purpose and audience.

  • Community: Guidelines and resources for community engagement.
  • Blog: Changelogs, feature introspections, and relevant articles.
  • Docs: Technical documents, API references, installation, and configuration guides.

Automated Document Generation & Deployment

Automation is the cornerstone of efficient documentation management. We've instituted tools and workflows to simplify document creation and deployment:

• Automation Tools: On Mac and Linux platforms, we employ make and gendocs to automate certain documentation processes.

  • Example: The following command auto-generates multilingual markdown documents and their foundational templates.

    make new-post POST_NAME="openim-offline-deployment-design"

• Testing & Deployment: GitHub actions test the documents, generating test reports. Additionally, a DevOps workflow ensures documentation accuracy and relevance.

  • Upon passing tests, GitHub actions deploy these, synchronizing with Netlify. Netlify then completes the deployment, rendering the corresponding web pages.
  • Notably, https://netlify.app/ leverages plugins for accelerated access in regions like China.

Bidirectional Document Synchronization Strategy

In multi-repository management, bidirectional document synchronization is challenging. We've devised the following solution to streamline this process:

• Webhook Integration:

  Webhooks link the directories of

  GitHub openim/website

  with sub-repositories like openim-server and openim-chat :

  • Modifications made to markdown documents in these sub-repositories automatically reflect in the website repository, eliminating manual maintenance and synchronization, thereby enhancing efficiency.

In summary, this strategy offers a comprehensive guide and toolset for document management, automated deployment, and bidirectional synchronization. This not only guarantees document precision and quality but also significantly elevates the team's productivity.

[cubxxw]

OpenIM 站点结构设计

• 站点的地址：https://openim.io/
• 代码仓库的地址：https://github.com/openim/website

OpenIM 是一个开源的社区，和传统的官方网站有所区别，对网站的要求更高，不管是文档的质量，以及代码的要求要更加的严格。我参考 Kubernetes 的官方社区网站 http://kubernetes.io/ 为 OpenIM 提供了一些设计技巧。

OpenIM 的遗留问题

• 文档优化的 issue：📚 Reverse the rewrite of OpenIM-Docs #384

自从脚本目录重构后，文档成为了 OpenIM 存在的问题。

• 接口文档不够自动化，没有及时更新，可信度问题。
• 部署文档远远落后，出现部署报错问题
• OpenIM 社区文档少之又少，非常不利于开发者上手，贡献者贡献。
• OpenIM 的社区文档难以向国际化、专业化迈出脚步。
• OpenIM 文档的文档仓库不规范，缺乏文档 README，难以上手，没有自动化功能。
• OpenIM 的文档和各个仓库的紧密度不高，开发者开发代码，难以关注文档。
• 缺乏其他语言的文档，文档的架构设计不是特别好。
• 没有一套专业的流程（贡献，策略，方法指南）

我为 OpenIM 设计了最主要的几个模块：

• Blog: OpenIM 的博客（一些最新的博客，一些精选的文章）
• Docs：OpenIM 的体系文档
• Community：OpenIM 的社区生态（周会，周边，线下交流…)

重要的设计细节

考虑长期的维护力度以及参与度，我对整个 OpenIM 的站点设计有着很高的要求：

1. 用户界面 (UI)：
   • 颜色方案： 主色调采用深蓝色，代表技术与稳重，配合灰色或白色作为辅助色，以保持简洁和专业感。
   • 响应式设计： 适配各种屏幕大小，确保无论是桌面，平板还是手机，用户体验都是一致的。
   • 用户导航： 顶部导航栏清晰地展示“Blog”、“Docs”和“Community”三大模块，方便用户快速访问。
2. Blog 模块：
   • 特色文章： 在首页或博客主页面展示最新和精选的文章，以吸引用户关注。
   • 分类与标签： 方便用户按兴趣或主题进行浏览。
   • 评论功能： 用户可以在每篇文章下方留下评论，以促进交流和反馈。
3. Docs 模块：
   • 分层结构： 文档应分为“入门”，“高级”和“API 参考”等级别，帮助不同水平的用户找到合适的内容。
   • 搜索功能： 允许用户快速查找相关的文档内容。
   • 版本管理： 随着 OpenIM 的版本更新，文档也应有版本控制，方便用户查找到相应版本的文档。
4. Community 模块：
   • 活动日历： 显示即将到来的双周会、线下交流等活动日期和细节。
   • 会员展示： 展示活跃的社区成员或贡献者，以鼓励更多人参与。
   • 资源链接： 提供与 OpenIM 相关的工具、插件和其他资源的链接。
5. 其他考虑：
   • 多语言支持： 考虑到 OpenIM 可能是国际性的社区，提供多语言支持会增加其受众范围。
   • 访问速度： 确保网站加载速度快，为此可以采用 CDN、代码优化等技术。
   • 安全性： 保护用户数据和网站内容不被恶意攻击或滥用，例如使用 HTTPS 和定期进行安全审查。

文档自动化与同步管理方案

文档分流与设计

对于一个大型项目或多个项目的整合，文档的管理和组织是至关重要的。通过对文档的分流，我们可以有效地为不同的目标读者提供所需的信息：

• 文档抽象层设计: 对于文档结构，我们进行了大量的设计工作，以确保每个部分都有明确的目的和读者。
  • Community: 社区交流和参与的指南和资料。
  • Blog: 更新日志、新功能介绍以及相关文章。
  • Docs: 技术文档、API参考、安装与配置指南等。

自动化文档生成与部署

自动化是实现高效文档管理的关键。我们提供了一套工具和流程，使文档的生成和部署变得简单：

• 自动化工具: 在Mac和Linux环境中，我们使用make和gendocs工具，对部分文档进行自动化生成。

  • 示例: 使用以下命令可以自动生成多国家的markdown文档及其基础模板。

    make new-post POST_NAME="openim-offline-deployment-design"

• 测试与部署: 利用GitHub actions对文档进行测试，并记录测试报告。此外，我们还设计了DevOps工作流，确保文档的质量和更新的准确性。

  • 一旦文档通过测试，我们使用GitHub actions将其部署，并与netlify同步。netlify会自动完成其部署，从而生成相应的网页。
  • 值得一提的是，https://netlify.app/在国内通过插件加速，保证了访问速度。

文档双向同步方案

在多仓库管理中，文档的双向同步是个挑战。我们设计了以下方案，以简化此过程：

• Webhook链接: 通过webhook，我们链接了GitHub openim/website的各个目录与各个子仓库（例如openim-server, openim-chat）。
  • 当在这些子仓库中对markdown文档进行修改时，这些更改会自动同步到website仓库中。这消除了手动维护和同步的需求，大大提高了效率。

[kubbot]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[kubbot]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[kubbot]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.