Dev docs & specs - Githubissues

Lemmingh commented 4 years ago

What is the problem

When trying to contribute to this project, it took me a lot of time to understand the part I'm interested in. I often have to trace back to figure out how a function came and why it's implemented in that way. And this is mainly why I prefer to join discussions rather than submit changes.

It would be great to have developer documentation explaining every design.

My proposal is posted in the next 2 comments.

Repo: https://github.com/markdown-all-in-one/docs

Kanban: https://github.com/users/Lemmingh/projects/2

TODOs

[ ] Migrate existing FAQs + how to deal with performance issues
[x] Sidebar
[ ] SEO. vuepress-plugin-seo can add Open Graph metadata. But to generate canonical URL is awkward, and I make it in an ugly way now. Besides, it would be ideal to have other formats, such as JSON-LD.
[ ] Accessibility. The contrast ratio of <a> elements is only 2.75. However, WCAG AA recommends 4.5 at least. Perhaps we need to tweak the theme.

Lemmingh commented 4 years ago

The `docs` folder

Example:

docs/
+-- decisions/
    +-- compatibility-with-other-extensions.md
    +-- key-binding.md
    +-- localization.md
    +-- markdown-preview.md
    +-- markdown-syntaxes-and-dialects.md
    +-- math-support.md
    `-- syntax-highlighting-for-fenced-code-blocks.md
+-- project-management/
    +-- automation-services/
        `-- ci.md
    +-- code-style.md
    +-- emoji.md
    +-- issue-management.md
    +-- labels.md
    +-- life-cycle.md
    +-- repository-organization.md
    `-- test.md
+-- specs/
    +-- list-editing/
        +-- list-continuation.md
        `-- list-toggling.md
    +-- math/
        +-- definitions-of-math-areas.md
        +-- math-environment-toggling.md
        `-- math-syntax-highlighting.md
    +-- markdown-table/
        `-- table-formatting.md
    +-- table-of-contents/
        +-- detecting-toc.md
        +-- generating-toc.md
        +-- gitea-slugify-rules.md
        +-- github-slugify-rules.md
        +-- github-enterprise-server-slugify-rules.md
        +-- gitlab-slugify-rules.md
        +-- hugo-slugify-rules.md
        `-- vscode-slugify-rules.md
    +-- code-completion.md
    +-- exporting-to-html.md
    +-- markdown-preview.md
    +-- pasting-link.md
    `-- syntax-decorations.md
`-- CONTRIBUTING.md

In case the docs folder is published to a website some day, all the entry names are in lowercase except special files like CONTRIBUTING.md, and words are connected by hyphen. If there is no such need, I would recommend the Microsoft Style or the Chicago Style capitalization.

Besides, the names are nouns.

`decisions`

Decisions on what should or should not be implemented, or general guidelines.

`project-management`

Conventions and maintainers' behavior.

`specs`

Specifications of features, describing the current design.

`CONTRIBUTING.md`

A basic contributing guide for everyone.

Lemmingh commented 4 years ago

JSDoc in source code

It's a good practice to document every function and type using JSDoc next to implementation, or in declaration files for large libraries.

In this way, developing experience can be improved, and if needed, API docs can be auto-generated.

For functions, function, parameter and return descriptions should be provided.
For types, a brief description of the type is enough for many projects, I think.

However, lots of code in this project lacks enough documentation, thus, new contributors may have to read entire implementation to understand a function, even if it's trivial and not essential to their work. Besides, existing JSDoc annotations are not consistent in style.

Actually, reading code related to a feature is a nightmare to some degree for me. I don't think I can conclude the role of a function just from its name.

yzhang-gh commented 4 years ago

Thanks for the hard work!

It's true that this extension now becomes a relatively big project and definitely needs a better documentation. We have seen other projects using, for example, GitHub Wiki, or standalone docs sites.

The same goes for JSDoc, although I didn't expect there would be many contributors 😅. (Or they can just ask me.)

I am happy that you bring up these problems but I guess this will take a long time (maintaining docs is always a dirty work). I would suggest us start with the most confusing parts and improve the docs gradually.

Lemmingh commented 4 years ago

I've created a repository: https://github.com/Lemmingh/vscode-markdown-docs

A separate docs repo could provide good flexibility.

I can transfer it to you later.

Priority

I would suggest us start with the most confusing parts and improve the docs gradually.

I guess hot topics are:

decisions/compatibility-with-other-extensions.md
decisions/markdown-syntax-and-flavors.md
decisions/syntax-highlighting-for-fenced-code-blocks.md
specs/math
specs/table-of-contents
specs/exporting-to-html.md

Deployment

We have seen other projects using, for example, GitHub Wiki, or standalone docs sites.

There are indeed a number of ways. To name a few (in alphabetical order):

Build
- Hexo
- Hugo
- Jekyll
- MkDocs
Host
- GitHub Pages
- GitHub Wiki
- Read the Docs

It appears that many platforms are compliant with CommonMark and GFM.

I suggest writing in a neutral and restricted way for now, and discuss the publish plan later.

License of docs repository

Please.

yzhang-gh commented 4 years ago

Thanks. I would suggest Vuepress + GitHub Pages 😏.

I've created a repository: https://github.com/Lemmingh/vscode-markdown-docs

A separate docs repo could provide good flexibility.

I can transfer it to you later.

Great. And you can just keep it. Probably we can add it as a submodule.

yzhang-gh commented 4 years ago

我把 vuepress 设置好了，你可以把 GitHub Pages 设置到 gh-pages 分支看看效果，要是觉得还行的话就可以暂时用着

Lemmingh commented 4 years ago

配置文件的名字应当是 config.js。😅

https://lemmingh.github.io/vscode-markdown-docs/

已知问题

<a> 的对比度仅有 2.75。可能需要调 theme 以改善无障碍性。
参考 VuePress 官方站的配置，设置一套丰富的 sidebar 似乎较难。
SEO. 我尝试用 vuepress-plugin-seo 添加 Open Graph 元数据，但在处理 canonical URL 上遇到了困难。此外，还需要寻找办法添加其他格式的元数据。

顺便一提，GitHub Pages 最近的这次更新让我有点迷茫。

yzhang-gh commented 4 years ago

配置文件的名字应当是 config.js。😅

🤣

https://lemmingh.github.io/vscode-markdown-docs/

👍

已知问题

可以放到最上面备忘（我随便按优先级排一下）

顺便一提，GitHub Pages 最近的这次更新让我有点迷茫。

看起来就是说可以任意选一个分支 publish，我们把 dist 里面的文件都丢进去就好了？

总的来说我觉得有胜于无，内容先放上去，其它的随缘改进🤪

彩蛋

https://github.com/yzhang-gh/vscode-markdown/blob/3edd76877491782f33552999d2897869b50dc90c/src/print.ts#L183-L186

Lemmingh commented 4 years ago

GitHub Pages

按我的理解，这次主要是 3 处改变：

可以使用任意 branch。
可以使用根或 docs 目录。
当 gh-pages 存在时，无法关闭 GitHub Pages。

把 dist 里面的文件都丢进去？

我现在就是这样处理😂

https://github.com/Lemmingh/vscode-markdown-docs/blob/6e710ab49cc80a34eee3ad56098f6ff5e5137609/tools/Deploy-Website.ps1#L99

https://github.com/yzhang-gh/vscode-markdown/blob/3edd76877491782f33552999d2897869b50dc90c/src/print.ts#L183-L186

这应该问题不大。

如果想做得很精确，需要先解决 #552 #636 https://github.com/yzhang-gh/vscode-markdown/issues/570#issuecomment-596607336 #531 之后才能更新 TM grammar 和这里的匹配规则。

我怎么感觉问题已经复杂到需要写个 language server 了😨

可否请你先编写 Writing style guide docs/project-management/docs-management/writing-style-guide.md

我根据这边的文件猜了一下风格，但是很拿不准。

yzhang-gh commented 4 years ago

可否请你先编写 Writing style guide docs/project-management/docs-management/writing-style-guide.md

我根据这边的文件猜了一下风格，但是很拿不准。

我倒是没什么很特别的要求，一般是别人 PR 之后我再手动调一下（毕竟有些细枝末节的习惯就算写成文档别人也不一定会认真看，直接顺手改了不用纠缠）但是既然提到了我也想想写一点吧

Edited: 你好像是说 Markdown 的风格。。。（那我甚至建议可以用 markdownlint 这个插件，选择好里面的规则）

另外现在的结构（Decisions，Management，Specifications）我感觉有点不直观，可以先分成用户与开发者两大类（For users，For contributors），用户文档介绍本插件有哪些功能，没有哪些功能 等，开发者文档介绍代码结构，代码格式等。这样大家看文档的时候可以直接找到感兴趣的位置。

Lemmingh commented 4 years ago

https://github.com/Lemmingh/vscode-markdown-docs/commit/f9f72011ec3e4da1b7dfe3d1a7bb7abea04f07cf

Guide          + New user
               |
Decisions      + Advanced user
               |
Specifications + Contributor
               |
Management     + Maintainer
               ↓

yzhang-gh commented 4 years ago

Lemmingh/vscode-markdown-docs@f9f7201

👏👏👏 有时间我看着也补充一些。

另外我注意到了注释的样式，顺便可以分享一下我个人的习惯，// 表示注释掉的代码，//// 用来写真正的注释文本，我自己在 VSCode 里面是用了 Highlight 插件来区分这两者

Guide          + New user
               |
Decisions      + Advanced user
               |
Specifications + Contributor
               |
Management     + Maintainer
               ↓

Guide 和 Management 我觉得很好理解，但是 Decisions 和 Specifications 就有点突兀（貌似没看到过其它文档把这些作为一级目录？）不过我倒没太大意见，先这么着呗

Lemmingh commented 4 years ago

注释的样式

咱俩的习惯可能刚好反着。😂

我是在注释的内容前缀记号：

Prefix	Meaning
`!`	Warning
`?`	Question
`//`	Delete
`TODO:`	Todo

于是

// This is a normal comment.

//// Discarded code.

// ! Be cautious.

// ? How to improve it?

现在加了用户文档 (User guide)，需要开 LFS 吗？我担心如果进来许多图片，体积可能会膨胀很快。

yzhang-gh commented 4 years ago

// This is a normal comment.

//// Discarded code.

你这就不科学了，uncomment 的时候代码需要 uncomment 两次，文本倒只需要一次🤓

现在加了用户文档 (User guide)，需要开 LFS 吗？我担心如果进来许多图片，体积可能会膨胀很快。

感觉有点杀鸡用牛刀，png 格式的截图总共也没多大

Lemmingh commented 4 years ago

算是……习惯问题？

你的方式，删代码仅用单纯注释，在调试时比较方便。（某些调试时应该都会这样做吧？）

而我倾向于：

绝大多数时候，我的注释用来写人话，而且容易写很多。简单起见，默认注释内容是人话。
我在 commit 前会清理代码。保留已删除的内容的情况很少出现，除非我确信马上会再用到它。
我需要普适多种语言的模式。这里也要考虑视觉，尽量少引入负担。
- C# 中的 XML documentation comments （类似于 JSDoc）以 /// 开头。
- XML、HTML、CSS 等只有 block comment。
- YAML、TeX、Windows Batch 等只有 line comment。

yzhang-gh commented 4 years ago

算是……习惯问题？

对，每个人偏好不同而已，我仅仅是随手一评论。不过你有个点说对了，我是平时跑实验要调试的代码很多，所以有这种偏好（写 Python 实际用的是 # 和 ##）

Lemmingh commented 3 years ago

Questions about labels

I'd like to know the differences:

Question vs. Discussion
Feature request vs. Enhancement

And it appears that we have different taste for colors:

You prefer light colors, while I like high contrast.

Do I understand correctly?

yzhang-gh commented 3 years ago

I'd like to know the differences:

Question vs. Discussion

Feature request vs. Enhancement

For me, question means user questions, e.g. they probably didn't know about some features. discussion is used when I haven't yet decided whether a user request will be considered a valid feature request. This usually needs more feedback from other users.

And it appears that we have different taste for colors:

You prefer light colors, while I like high contrast.

This is because I found using black as the foreground color feel visually cleaner to me

https://github.com/microsoft/terminal/issues

Lemmingh commented 3 years ago

I see. Then, Feature request vs. Enhancement?

Feature request for something totally new, while Enhancement for existing features?

yzhang-gh commented 3 years ago

Feature request for something totally new, while Enhancement for existing features?

💯

Lemmingh commented 3 years ago

OK. My next questions are related to emojis.

AFAIK, emojis used here are based on gitmoji. However, we seem to have evidently different understanding of some.

The following confuse me most.

When to use :twisted_rightwards_arrows: (U+1F500)

:twisted_rightwards_arrows:\ Merge branches.

You appear to add it every time merging a PR.

In my view, it's for merge commits only to easily identify those three-way merges (aka. basic merge; true merge). As for squash merge, other emojis would be nicer.

What's your opinion?

The meaning of :speech_balloon: (U+1F4AC)

:speech_balloon:\ Add or update text and literals.

I feel this overlaps others greatly, and personally don't use it.

:recycle: (U+267B) and :truck: (U+1F69A)

:recycle:\ Refactor code.

:truck:\ Move or rename resources (e.g.: files, paths, routes).

A similar problem. I tend to use :art: (U+1F3A8) and :building_construction: (U+1F3D7) instead.

Do you have any suggestions?

:green_heart: (U+1F49A)

:green_heart:\ Fix CI Build.

Emmm ... Again. Why not :construction_worker: (U+1F477) or :white_check_mark: (U+2705)?

yzhang-gh commented 3 years ago

Sometimes the reality is much complicated than what can be expressed by a set of emojis. We can try to make a consensus but for some corner cases let's be flexible.

When to use 🔀 (U+1F500)

I guess we will never do other kinds of merges than squash merge? Of course we can use two all more emojis if needed.

The meaning of 💬 (U+1F4AC)

Sometimes it is hard to find a better emoji. I think it at least says the commit is text-related (better than nothing).

A similar problem. I tend to use 🎨 (U+1F3A8) and 🏗️ (U+1F3D7) instead.

I haven't used ♻️ for a long time. I use 🎨 mainly for code formatting (visually), but I have no objection against it being used for refactory. 🏗️, I don't remember but I might have used it for refactory. 🚚, I think it's fine.

💚

I would say 💚 is "fix CI build" in general (e.g. the workflow file), while ✅ is more related to unit tests. 👷, seems I haven't used it.

Lemmingh commented 3 years ago

I've split a few Area labels:

List continuation -> List editing, Task list, Block quote
Preview styles -> Styles and Presentation, Preview
Table of contents -> Table of contents, Link

yzhang-gh commented 3 years ago

LGTM

Lemmingh commented 2 years ago

Area "Docs" and "UI" may also need splitting. Any suggestions?

yzhang-gh commented 2 years ago

I don't see the necessity, not sure what else areas you have found.

yzhang-gh / vscode-markdown

Dev docs & specs #765

What is the problem

TODOs

The `docs` folder

`decisions`

`project-management`

`specs`

`CONTRIBUTING.md`

JSDoc in source code

Priority

Deployment

License of docs repository

已知问题

Questions about labels

When to use :twisted_rightwards_arrows: (U+1F500)

The meaning of :speech_balloon: (U+1F4AC)

:recycle: (U+267B) and :truck: (U+1F69A)

:green_heart: (U+1F49A)

yzhang-gh / vscode-markdown

Dev docs & specs #765

What is the problem

TODOs

The docs folder

decisions

project-management

specs

CONTRIBUTING.md

JSDoc in source code

Priority

Deployment

License of docs repository

已知问题

Questions about labels

When to use :twisted_rightwards_arrows: (U+1F500)

The meaning of :speech_balloon: (U+1F4AC)

:recycle: (U+267B) and :truck: (U+1F69A)

:green_heart: (U+1F49A)

The `docs` folder

`decisions`

`project-management`

`specs`

`CONTRIBUTING.md`