Part 1: doc restructure, introduce categories #1364
Conversation
Based in the Diátaxis doc framework, we identified tutorials, how-to guides/recipes, addednum, and references. This commit deals with moving the topics into the "right" category. Related to issue lark-parser#1360
The first page should be clean and simple. It acts as a "hub" to let readers select what they need. Move all links into an additional resources.md file and add it to addendum.
tomschr
force-pushed
the
1360-doc-restructure
branch
from
432eda0
to
7bf9f9a
Compare
Tell the reader how the Lark documentation is organized. This makes it easier for the reader to choose the necessary topics.
|
docs/index.rst
Outdated
| ------- | ||
|
|
||
| How the documentation is organized | ||
| ---------------------------------- | ||
|
|
||
| A high-level overview of how it’s organized will help you know where to look for certain things: | ||
|
|
||
| .. _Sublime Text & TextMate: https://github.com/lark-parser/lark_syntax | ||
| .. _Visual Studio Code: https://github.com/lark-parser/vscode-lark | ||
| .. _Intellij & PyCharm: https://github.com/lark-parser/intellij-syntax-highlighting | ||
| .. _Vim: https://github.com/lark-parser/vim-lark-syntax | ||
| .. _Atom: https://github.com/Alhadis/language-grammars | ||
| * Tutorials take you by the hand through a series of steps how to get familiar with Lark. Start here if you’re new to Lark. | ||
| * How-to guides are bite-sized, problem-specific solutions to common tasks. | ||
| * Addendums covers background information to Lark. | ||
| * References contain syntax and semantics reference material for Lark. |
There was a problem hiding this comment.
I personally don't really like if documentation feels the need to explain how it works. The naming of sections should be good enough that it's obvious. This is IMO the case for Tutorials, Addendum and References. How-to is a bit less clear, Recipes is a better name there IMO.
Even if we keep this list, the first sentence that explains that this is an explanations of sections is definitely not needed and just represents noise.
There was a problem hiding this comment.
That's a fair point. Actually, I had stolen this part from the Django documentation. Maybe for the Django docs it's justified as their work is huge.
I have no problem to remove it, but let's give it a bit more time to see what others think about this.
Exactly. I think we can configure Sphinx to show more content for the left sidebar/TOC. In that case, the TOC in the content would be useless and could be removed. After I researched this issue, it can be done by adding the following lines: diff --git i/docs/conf.py w/docs/conf.py
index aacf8bb..405af4d 100644
--- i/docs/conf.py
+++ w/docs/conf.py
@@ -102,7 +102,8 @@ html_theme = 'sphinx_rtd_theme'
# documentation.
#
html_theme_options = {
- 'prev_next_buttons_location': 'both'
+ 'prev_next_buttons_location': 'both',
+ 'collapse_navigation': False,
}
I see. As a first time contributor, I was puzzled. Usually, writers (and probably contributors as well) don't want to deal with two formats. It's just makes live harder as you have to switch context (MD <-> RST). I've read the issue you gave me, but I'm still a bit confused. It's for historical reasons, okay. Are we forced to keep it? If not, can we use one format? Or are there any objections? At this point, we have the following options:
Apart from the above change, I realized there might be another question to consider. The current structure under For example, we could create It's your project, I'll give you just some ideas to think about. 🙂 If you think this would be beneficial, I'm willing to work on it. What do you think? |
Remove TOC in content as the left TOC sidebar contains [+] markers to unfold/fold the deeper structure.
We can convert the markdown files to rst, I have no objections (erezsh might). The point is more that we don't/didn't consider it worth the effort to convert them. But I don't think that should happen in this PR.
Sure. But IMO this should also be a separate PR to keep them all manageably small. Let's wait for erezsh to add their opinion. |
|
Thanks MegaIng for your comments! I agree with you. If we want to go this extra mile, I can do that in separate PRs. I'll wait for erezsh's opinion. Thanks! 👍 |
|
I see no advantages in having two formats at the same time. Just some additional thoughts:
|
|
@tomschr Thanks! Sorry to keep you waiting. I've actually been on vacation these past 3 weeks, and might have a bit more free time in a week or two. |
|
Thank you! Hope the vacation was fantastic! 😄 No problem, have a good day. |
|
Hi @tomschr , I got to looking at your branch. There were some changes I liked, and some that I didn't understand. More importantly, looks like your changes from the docs. This is how it looks when I build your branch locally:
Also, looks like you intentionally removed all the links from the index page. I think that's wrong. It's arguable how much links should be there, but definitely there should be a few "call to actions" for the most common pages users would like. |
|
@erezsh Thank you for your time! I'm sorry, it seems I had accidentally committed my last experiment. That shouldn't be the case, I've corrected the TOC now. Could you check again? |
|
@erezsh Any additions, corrections, or suggestions from your side? |
|
Sorry, I've been busy. If it was as simple as just merging it, I would have already done so. I will need to take the time to write my thoughts in detail, and explain what I think needs changing and why. I will try to get to it soon! |
|
@tomschr Sorry again for the long wait. At an overview, I agree with these changes, but not with all of the choices you made. A few points:
( I might be persuaded that it should contain the beginner examples, but I think examples should be together. Probably in their own separate section )
|
|
Thank you for your response! After such a long time it's hard to remember all the details that I made and the reasons behind it. 😆
That is true, but as we don't have these guides yet I had to put at least something. Keep in mind, we are just migrating from one structure to a new one. It's an intermediate step, it's not the end. We can always adjust it later. If you prefer to move these things, I can do that. But then we maybe end up with only one article under "First steps".
I did it on purpose, because "working" is a verb and means action. The problem with starting with "How to..." is, it propagates quite fast and you have other articles with very similar titles. That makes it harder for the reader to distinguish them. The difference in each title appears too late. In my work as a professional writer, I try to avoid starting with "How to..." if possible.
That shouldn't be a problem to move them. I'll do that later.
I'm not sure I got that. Any examples? Thanks for your time! |
|
No need to thank me! I'm glad you're trying to contribute to Lark, and like I said, I'm sorry it took so long.
Now you get a glimpse of how I feel about docs I wrote 4 years ago :)
That is acceptable. I think it's better than a mis-categorization, that might confuse a newcomer. We can also include the "How to write a DSL" tutorial as an external link.
Maybe there's a third option. Like "A guide to using Lark" or "best-practices for using Lark", etc.
Well, I wrote it as a "quick-links" section. Since you moved it as-is, it contains links to sections that are not really resources, like "philosophy", "features", and "examples". Also, some of these "resources" are either guides, or examples, or something in between, and would probably fit there better than to "resources". |
* Move some sections - parsers -> Reference - features -> Reference - examples/index -> How to guides
Haha, no problem. Now I had to say sorry as I wanted to work on it last week.
Haha, very true!
This is done in commit c3470e1 now.
Okay, no problem.
Hmn. 🤔 My idea was all about consistency: References and conceptual topics are in nominal style ("Grammar Reference", "JSON parser" etc.) whereas task-oriented topics uses verbs ("Contributing to Lark", "Working with Lark" etc.). Perhaps "Working" isn't the best verb and it can be improved. Your suggestion "A guide to using Lark" or "Best-practices for using Lark" just adds more fluff to the title. 😉 From my point of view, it's just too wordy. 😉 Whether it's a guide or a section doesn't really matter to the user. It's an implementation detail. The readers want to know what is the topic about and they want to understand it fast. Anything that distracts the user reduces their understanding. 😉 Just wanted to tell you my reasoning and why I think it matters. If you really want to go with your suggestion, I can do that change of course. 🙂
Yes, I moved it "as-is" to reduce the impact of the changes. Remember, it's part 1. In this part I deal only with restructuring, maybe correcting titles here or there, but not touching the overall text. This could be done at a later point. But perhaps I misunderstood you. |
I appreciate consistency, but I think clarity is even more important. "Working with Lark" isn't a terrible title, but I feel that it doesn't communicate well what the content might be. If I was looking for best-practices, I might miss it if I was trying to scan the menu. Anyway, I don't feel that strongly about it.
It's good to keep the changes small. But I don't want the docs to end up looking wrong or broken, even if it's temporary. If you're still confused, I can try to fix that page myself. But it needs doing. |
I see what you mean. But the titles work in combination with the guide title. I think we are talking about different things:
From what I see, I think these are different guides. If you have this distinction, you can focus on your titles. Beginner will be attracted by "First steps", more advanced users will gravitate the Best Practices or other guides.
Sure, absolutely. 👍
If it's not too much to ask for, please go ahead. |
Based on the discussions from #1360, this PR contains the following changes for part 1:
resources.mdfile.I've compiled it with
make htmlbut got some warnings. However, it seems, they exist in the master branch as well.Let me know what you think, @erezsh.
Open questions
When I worked on this PR, I stumbled upon the following issues:
Using different formats in one doc makes it hard to stay consistent. Both have a different set of syntax and features. What works with one doesn't work for the other.
IMHO, this makes it also hard to contribute. But this is for a different PR (if any), but I would really recommend to use only one format.
Result