Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

[DOC] Update work-with-vscode.md #38

Merged
merged 2 commits into from
Dec 30, 2024
Merged

Conversation

jamesnulliu
Copy link
Member

@jamesnulliu jamesnulliu commented Dec 29, 2024

Fixes #37

@Errant404
Copy link
Member

使用文本作为示意图是否过于抽象?
建议建立目录 docs/work-with-vscode,Markdown 文档重命名为 README.md,然后图片直接放在 README.md 同名目录中或者在该目录下另建 img 文件夹

@jamesnulliu
Copy link
Member Author

图片资源在发布 release 的时候不应该被打包 (以减少 zip 的大小), 而这会导致 release 包中 doc 不完整.

因此我认为:

  1. 使用文本作为示意图在 指出 vscode 按钮位置 的情况下是相对合适的方式.
  2. 本项目的文档应该趋于精简, 尽可能减少需要图片辅助的情况.

然而目前已知的问题在于:

  1. 某些字符比如 在非等宽字体的渲染下占位超过正常字符的宽度.

在使用 字符画 代替图片的方案得到认可后, 我会进一步改善上述问题.

@Errant404
Copy link
Member

图片资源在发布 release 的时候不应该被打包 (以减少 zip 的大小), 而这会导致 release 包中 doc 不完整.

我也考虑到了这一点。对此,我有两个观点,一个是我认为文档是否可以仅提供在线浏览,docs 不打包进 release,或者干脆直接迁移到仓库的对应的 Wiki 处,因为文档规模并不大,并且文档的性质是 tutorial 而非 reference,用户可能几乎没有本地浏览的需求;另一个是我觉得目前 docs 下图片可能的占用并不会特别大,至少不会超出 Overleaf 上传大小限制。

@jamesnulliu
Copy link
Member Author

jamesnulliu commented Dec 29, 2024

我也考虑到了这一点。对此,我有两个观点,一个是我认为文档是否可以仅提供在线浏览,docs 不打包进 release,或者干脆直接迁移到仓库的对应的 Wiki 处,因为文档规模并不大,并且文档的性质是 tutorial 而非 reference,用户可能几乎没有本地浏览的需求;另一个是我觉得目前 docs 下图片可能的占用并不会特别大,至少不会超出 Overleaf 上传大小限制。

开启 wiki 似乎是一个好主意, 但是需要考虑 wiki 的编辑权限问题. 如果只有管理者可以编辑, 其他用户将难以对文档内容进行贡献.

相反, 尽管目前 docs 下图片内存占用不大, 我认为将 tutorial 相关的图片打包入 release 并不是一个有建设性的选择.

@Errant404
Copy link
Member

开启 wiki 似乎是一个好主意, 但是需要考虑 wiki 的编辑权限问题. 如果只有管理者可以编辑, 其他用户将难以对文档内容进行贡献.

image

@jamesnulliu
Copy link
Member Author

image

我认为不选择 Restrict editing 能够解答我的担忧, 因此我赞同开启 wiki.

请不要关闭 #38 , 我将进一步:

  1. 删除 docs 下的新增文件.
  2. 在 wiki 处更新文档.
  3. 对 README.md 重新更新.

@jamesnulliu
Copy link
Member Author

jamesnulliu commented Dec 30, 2024

  1. 删除 docs 下的新增文件.
  2. 在 wiki 处更新文档.
  3. 对 README.md 重新更新.

dac7c8b 完成了 1 和 3, 同时 2 已经更新于 Wiki: Work with VSCode.

#36#37 的具体描述也更新为 "在 wiki 页增加文档".

@Errant404

@Errant404 Errant404 merged commit 07af232 into shuosc:master Dec 30, 2024
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[FEATURE] 使用 VSCode 集成环境的帮助文档
2 participants