cubxxw
commented
1 year ago OpenIM 站点结构设计
- 站点的地址：https://openim.io/
- 代码仓库的地址：https://github.com/openim/website
OpenIM 是一个开源的社区，和传统的官方网站有所区别，对网站的要求更高，不管是文档的质量，以及代码的要求要更加的严格。我参考 Kubernetes 的官方社区网站 http://kubernetes.io/ 为 OpenIM 提供了一些设计技巧。
OpenIM 的遗留问题
自从脚本目录重构后，文档成为了 OpenIM 存在的问题。
- 接口文档不够自动化，没有及时更新，可信度问题。
- 部署文档远远落后，出现部署报错问题
- OpenIM 社区文档少之又少，非常不利于开发者上手，贡献者贡献。
- OpenIM 的社区文档难以向国际化、专业化迈出脚步。
- OpenIM 文档的文档仓库不规范，缺乏文档 README，难以上手，没有自动化功能。
- OpenIM 的文档和各个仓库的紧密度不高，开发者开发代码，难以关注文档。
- 缺乏其他语言的文档，文档的架构设计不是特别好。
- 没有一套专业的流程（贡献，策略，方法指南）
我为 OpenIM 设计了最主要的几个模块：
- Blog: OpenIM 的博客（一些最新的博客，一些精选的文章）
- Docs：OpenIM 的体系文档
- Community：OpenIM 的社区生态（周会，周边，线下交流…)
重要的设计细节
考虑长期的维护力度以及参与度，我对整个 OpenIM 的站点设计有着很高的要求：
- 用户界面 (UI)：
- 颜色方案： 主色调采用深蓝色，代表技术与稳重，配合灰色或白色作为辅助色，以保持简洁和专业感。
- 响应式设计： 适配各种屏幕大小，确保无论是桌面，平板还是手机，用户体验都是一致的。
- 用户导航： 顶部导航栏清晰地展示“Blog”、“Docs”和“Community”三大模块，方便用户快速访问。
- Blog 模块：
- 特色文章： 在首页或博客主页面展示最新和精选的文章，以吸引用户关注。
- 分类与标签： 方便用户按兴趣或主题进行浏览。
- 评论功能： 用户可以在每篇文章下方留下评论，以促进交流和反馈。
- Docs 模块：
- 分层结构： 文档应分为“入门”，“高级”和“API 参考”等级别，帮助不同水平的用户找到合适的内容。
- 搜索功能： 允许用户快速查找相关的文档内容。
- 版本管理： 随着 OpenIM 的版本更新，文档也应有版本控制，方便用户查找到相应版本的文档。
- Community 模块：
- 活动日历： 显示即将到来的双周会、线下交流等活动日期和细节。
- 会员展示： 展示活跃的社区成员或贡献者，以鼓励更多人参与。
- 资源链接： 提供与 OpenIM 相关的工具、插件和其他资源的链接。
- 其他考虑：
- 多语言支持： 考虑到 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仓库中。这消除了手动维护和同步的需求，大大提高了效率。
- 当在这些子仓库中对markdown文档进行修改时，这些更改会自动同步到
kubbot
中文设计稿
I have designed the key modules for OpenIM:
Critical Design Details
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.
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
makeandgendocsto automate certain documentation processes.Testing & Deployment: GitHub actions test the documents, generating test reports. Additionally, a DevOps workflow ensures documentation accuracy and relevance.
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
with sub-repositories like
openim-serverandopenim-chat:websiterepository, 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.