Replies: 4 comments 10 replies
-
|
A few points/answers to questions
I also tried looking at the Diátaxis docs. And they immediately fail: I looked for 20mins, read about 2 of the pages in full and skimmed over another 4... And I still have no idea what it is. A "framework for documentation" normally includes software that can be installed. This doesn't appear to be the case, so it isn't a framework in a software sense. Is it a mental model? A structuring plan? Or is it really just the content of the "How to use Diátaxis" page? (terrible name btw, including diacritics is going to make your product worse for everyone except a few who have it as their native language to refer to) (and the docs where IMO also filled with way to much fluff, as well as unnecessarily many links to "look who uses this" and "it's proven to work"). If it is really is just that one page, then I am not sure if a project wide consensus is needed to agree to use it. If you want to make PR that improve the documentation, then do that. Don't refer to the project, just justify the changes in the PR inside of the PR. (in fact, they explicitly don't want you to do what you have labeled as step 3.) If you have further specific questions about aspects of the target group or the use cases of lark, you are ofcourse free to ask them. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for your answer. However, I think you misunderstood my intention or I haven't addressed my idea clear enough.
It's written on the first page:
No, it's completely independent from any software. That is precisely what makes it so universal. It's a framework in the sense of a mental model. As such it defines these four types which users usually search.
Yes.
If you are finished with your rant we can discuss about the facts? 🙂 |
Beta Was this translation helpful? Give feedback.
-
|
Which we are already explicitly doing in for example the readme, the examples and some parts of the docs. You just want to have more of that? We generally split into two groups, people who don't a lot about parsing theory and those who do. |
Beta Was this translation helpful? Give feedback.
-
|
As I wrote in my other post, it's on GitHub, not in the documentation. People approach your project from different sites, be it links or search engine. The documentation doesn't have the target groups. |
Beta Was this translation helpful? Give feedback.
-
|
I am not going to further participate here. |
Beta Was this translation helpful? Give feedback.
-
|
@MegaIng That's okay. We're essentially talking about outreach, how to help newbies and non-programmers to learn Lark. I think it's a worthy goal, but not exactly critical for the project. P.S. I agree Diátaxis is not a great name :) |
Beta Was this translation helpful? Give feedback.
-
|
Hello @tomschr ! Thank you for this write-up. I appreciate you taking the time. It's always nice to get constructive criticism and suggestions. I agree with some of your points, but not all. I'll try address them in order -
The 4th line in the README reads:
And the answer immediately follows: Beginners & Experts. I do agree that this dichotomy isn't addressed throughout the documentation. And while the examples are split into 'basic' and 'advanced', other parts like the recipes are a mixed bag.
That's a good point. We should add a paragraph about that.
It's hard to think of a simpler scenario that is still realistic. What did you think of this as a tutorial? And how about this ? It was written for my old parsing library, but it would be very easy to adapt it to Lark, since the ideas are the same.
That's a good point too. I put it there when Lark was still an experimental library with a lot of unusual design choices, and I was afraid it might scare users away, and needed a justification. I think that's not longer relevant, now that Lark's position in the Python ecosystem is well-established.
Do you mean like "Collect all comments with lexer_callbacks" or "Keeping track of parents when visiting". Or something else entirely?
I've heard of it before, and I think it's an interesting idea. I do have some doubts about adopting it as an absolute system of organizing docs, but I definitely think it could be used for inspiration, and its recommendations taken along with other considerations. Overall I do agree that Lark's documentation could be better. It hasn't been updated in a long time, and it's showing. But the question that usually gets asked around this point, is who's going to update it? My to-do list and wish-list for Lark are long, and sometimes just staying on top of the issues and PRs can feel daunting, given that I have limited free time to spend on Lark. It's also the unfortunate case that almost all PR contributions come in the form of code, and very rarely in documentation. In fact I would even be happy to pay someone to help spruce up Lark's docs, but so far no candidate has presented himself or herself. I will try and carve some time to address the points I've already agreed to above, and I thank you again for bringing them to my attention. But I can't promise any big plans or migrations, at least not at present. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, @erezsh 👋 thank you for your answers. I'm happy to discuss your concerns with you. 🙂 Maybe we can learn from each other.
True, but that is in GitHub. But that's not enough. You have the assumption that people will always visit GitHub first. Some do, but this assumption is not always true. People can get redirected through search engines or links and boom, your reader/user doesn't know anything about target groups anymore.
Well, that's my point. You think too complicated. 😉 If the beginner is your target group then you have to take this group into account. A beginner is not interested in different parsers, customized lexers etc. They want a simple tutorial that leads you through the steps, to get familiar with the lib, and to get a "feeling" how to use it properly. By the way, this is where the doc framework can help. For example, we could parse simple data types as an example: ISO dates, unusual dates, phone numbers, postal addresses etc. Something like this. Sure, these could be done by simple regexes, but that's not the point. A beginner wants an example without distraction. It doesn't have to be overly realistic IMHO. Let's give them these simple examples and make them happy! If I add the Diataxis doc framework into account, this is what they say about a tutorial:
So maybe we need to rename the target group "beginners" to "learners"?
Much better! You already applied the principles from the doc framework: you explained things and created a procedure with steps. I like procedures! They conduct the user through these steps and they know where they are and what they have to accomplish.
Looks also good, but your first is better structured IMHO.
Thanks. This is exactly what I see it too: as an inspiration. May I ask what are you doubts?
Yes, this is what a lot of open source project have in common. I write documentation for over 20 years now and I have a theory. The simplest one (and I hear it a lot) that "documentation isn't sexy". I know, a lot of developers want to try the latest cool new feature, but rarely think about documentation. The more complex theory is, that maybe either the documentation is sufficient enough, people don't complain and put all their energy into code, or they don't know how to write and improve documentation? I would think, it's the latter. And this is why the doc framework can help. If you can explain how to contribute to it, people could be enabled to contribute to docs as well. Usually if you structure your documents into smaller pieces, it's more likely that people would write a similar piece. Most people learn from examples. If they copy existing code, they can adapt it to their needs. That's the same with documentation. Would like to hear your thoughts on this. |
Beta Was this translation helpful? Give feedback.
-
Fair enough, we can try to get the docs README to reflect the same crucial information as the code README.
I'll be happy to add a section of tutorials and links for complete beginners, under "New to parsing" or something of that sort. The remaining two are essentially "Know parsing; New to Lark" and "Know lark, don't know all the features and behaviors"
Nothing in particular, just that it doesn't address every need by our users. But that doesn't mean it can't be helpful!
That might be part of it. Also, a lot of documentation is about anticipating what other people might think or be unclear about, which isn't often in the arsenal of the average computer programmer. (although I believe it should be) |
Beta Was this translation helpful? Give feedback.
-
|
Okay, to make my abstract ideas a bit more specific, here is my suggestion. I've looked at the table of contents and tried to assign one of the four doc types to a topic. Hope you can see how this doc frameworks works. 🙂 I've identified these four types in regards of the Lark documentation. Tutorial / First steps-> Learning-oriented I think, some tutorials need to be written anew and the tutorial about JSON parser maybe a bit reorganized. The tutorials should propagate from easy to more advanced level of difficulty. Possible tutorials:
How-to Guides / Recipes-> problem-oriented Some of the "how to..." sections and of the recipes could be combined. Possible tutorials:
Explanations-> understanding-oriented If you don't like "Explanations" use a different word: addendum, appendix, amendment, additional information, ... Some parts that are neither tutorials, how-tos, or references could be moved there:
References-> information-oriented For the time being, that could be mostly stay unchanged.
Summary/ConclusionIf I'm not mistaken, this sounds more like moving and regrouping the existing documentation. To break it down into steps, I would suggest:
Probably step 1 is the easiest: we could just move them without rewriting the content. Step 2 + 3 need more work and can be done in different PRs. What do you think? Would that work? |
Beta Was this translation helpful? Give feedback.
-
|
Generally I don't see a problem with this, and actually it feels like very little will actually change. Adding new tutorials is great, but it's not a change in structure. The how-to section is essentially just the recipes. Unless I'm missing something. I don't agree that "features" belongs in explanations. I think it's important information that non-experts might want to know as well. It's definitely more introductory than the philosophy part, or explanation of the parsers. So, other than moving the philosophy part a bit deeper, and adding new tutorials, what change are you actually proposing? |
Beta Was this translation helpful? Give feedback.
-
Great, that's good news! 👍
That's absolutely fine.
I think I'll create a PR so you can see what I propose. As I wrote in my comment #1360 (comment) under "Summary/Conclusion", I think we should split this idea/issue into three parts. The first parts is solely about moving the bits and pieces and give it a more cleaner look. I'll prepare a PR for review. If you don't like it or think it does not benefit the docs, we can stop and no time is wasted. 🙂 The second and third part is more work, but it can be divided into sub tasks. I would suggest to discuss these parts when we are finished with the first PR. One step at a time. 😉 Would that be okay? |
Beta Was this translation helpful? Give feedback.
-
|
Sure, that sounds good! If I may suggest, let's split the changes into several commits,, so that we can pick and choose the acceptable changes. And maybe best to keep the PR small, as to not waste your time either, in case there is discord in our views. |
Beta Was this translation helpful? Give feedback.
-
|
Perfect! I've worked on it in PR #1364. I hope it is small enough and tried to make logical commits. Let me know what you need. |
Beta Was this translation helpful? Give feedback.
-
Hello Lark team, 👋
first, this is an awesome project and I like to thank you for all the hard and dedicated work! ❤️
I thought I start a discussion first instead of creating an issue. My idea was to gather some responses and see if this is something completely nonsense or if there is some interest. Hope this is okay. 🙂
Background
Just a few sentences about myself: In my professional career, I'm a developer and writer. I like to write code as well as documentation, so I care about both.
Over the last few years, I have gotten to know many great projects. They offer great features, are well-tested, stable, and are actively developed. But what they lack is their documentation is either non-existent or neglected. How should the user know how to use it? In my experience, developers are in most cases very good in writing code, but have problems writing good documentation. It usually requires a different perspective, and changing this perspective is difficult.
Observations
I recently came across this project and started to read up on it. When I approach a new project I usually have these questions:
I study the GitHub project page and consult the documentation to answer my questions. If I can find answers to my questions fast, I look closer.
When I looked closer at this project, I had some difficulties with the documentation.
I try to summarize my concerns. Of course, you are free to disagree 😉 here, but it mainly boils down to this:
Who is this project for? You would probably answer "it's for developers!" which is certainly true. 😉
However, not every developer is an expert. We have junior developers and senior developers. And maybe interested beginners who occasionally write programs as a hobby. All have different knowledge about this topic. Who do we write for? This isn't really spelled out nor explicitly mentioned.
The answer to this question is twofold: it acts as a guideance for the maintainers, writers, and contributors. Having a clear understanding about your target groups help to focus on what to include and what to exclude in your docs.
But it also helps to give readers/users a clear picture if this is something that is helpful for them.
As another target group, you have contributors. People who fix bugs, add new features, release it etc. There is some overlap, but it's better to distinguish these groups.
The project documentation never clearly defines what is needed in terms of what you need to know to use this library efficiently.
Related to this, important terms (EBNF, grammars, parser etc.) are not defined or are distributed throughout the docs.
The doc assumes you know this. That's fine, but as terms can be sometimes ambiguous, I would have liked to see how you understand and how you use these terms.
Although the first tutorial "JSON parser" gave me some insights, it was a bit too advanced for my taste. It describes things that I would expect in more advanced scenarios.
Maybe a more basic scenario would be helpful as an addition?
Starting the documentation with a philosophical overview, their design principles and choices is in my humble opinion not ideal. 😉 When people consult the docs, they want to learn, read tutorials, or want to know if this project can help to solve their use cases. They probably not want to read about why you designed this project the way it is now. This is maybe useful for a contributor, not for a user.
There are some awesome things you can do with lark. However, users who don't know much about this projects search for more basic recipes.
Additionally, it could be helpful to start a recipe with a problem that you want to solve. Currently, you answer the how it is solved, but not the what and why.
Idea
Ok, now as I laid out the issues that I see with the current documentation, how can this be addressed?
With a doc framework like Diátaxis!
It's actually not really difficult, but helps you in structuring your documentation. Every topic that is written is categorized into two axis:
This gives you four quadrants (taken from the homepage) which four document types:
The home page (link above) gives a more through explanation. But the basic principle is to categorize your text into one of these four quadrants to help to distinguish the content. The framework has the idea in mind that we need different types of documentation for different actions.
Programming and writing has a lot of in common. When you program something, you maybe also follow design patterns, clean code, etc. The doc framework is something similar and provides you with the means.
Benefits
If you are not fully convinced, maybe the following benefits could help to change your mind: 🙂
You can find under the section Who's using Diátaxis? which projects and organizations integrated this framework successfully.
What does that mean in practice?
This is certainly not something that can be done in a single pull request. It's more an ongoing goal towards a better structured documentation. As code, documentation may be complete, but never finished. 😉
How can this be addressed?
One way to do it could be something like this:
Familiarize with the doc framework
Familiarize yourself with the goals and the categories of the Diataxis documentation framework and where it can help.
Put yourself in the shoes of a user who approaches your project for the first time. What does such user need?
Define your target group
Which users do you want to attract? Beginners, experts, or both? What about contributors?
If you are unsure about your target group, start a poll and ask. Sometimes it helps to define personas when you have a clearer picture.
Asses your documentation
Try to categorize your existing work and understand its structure and content. Perhaps you see that a howto isn't clearly written or overlaps with another category or you find gaps?
Create a migration "plan"
Perhaps "plan" is a too overloaded word. A plan is usually outdated soon, change too fast, or is too complex. So better write a list based on the last step to rewrite, reorganize, or create new content. A list with action items can be converted into GitHub issues with a clear goal.
Iterate and improve
Refine the documentation and the migration plan/list. Rinse and repeat until happy. 😉
Decide what's most important
Coming back to my observations, try to answer the most important and pressing questions first.
Add these most important topics (quick starts, beginners guide etc) on the first pages.
What do you think?
Beta Was this translation helpful? Give feedback.
All reactions