Finisher example, start of a set of examples in the docs #42
Conversation
|
@matthew-carroll can you take a look? |
|
I don't understand the intention of this new example project. I'm not sure that such a project needs to be created. If it does, I'd like a lot more clarity as to what belongs there, and what doesn't belong there. We already have the docs project, which operates as a stress test for features. It also operates as an example of how to use static_shock. The docs project deploys a website that includes guides for how to accomplish common tasks. And then there's the generated API docs, too. So why do we want to maintain another example project? |
|
tl;dr: We should have short feature-specific examples for as much of static shock as possible because it helps devs and it provides snippets for API and guide docs (which also helps devs). The static_shock_docs site is a great real-world example and we should continue to use it to illustrate SS in the real-world and use it to stress test the framework itself. However, if I want to see how something specific works, e.g. finishers, I may or may not find that used in the static_shock_docs site source code in a sufficiently simple way for me to understand how it works so that I can apply it to my own problem. Likewise, the guides on the web site are fantastic, but they're incomplete w/ no backing source code for me to go find the rest of the details that make each one of them work. Also, unless that code is copied from a running project, it's going to get stale over time. The way to solve this problem is with a series of feature examples that illustrate the various features of SS in big-sized chunks that make it easy for devs to understand. What I'm proposing is not one more project (the finisher example) but 20 more projects (of which the finisher example is just the first one). As an example, Flutter has dozens (hundreds) of these examples and it's where they get the code to paste into their docs and source code as snippets. Snippets of simple, targeted example code are important. UX studies show that whenever a dev lands on a search result, the first thing they do is scroll for sample code looking for something they can copy-paste-edit to solve their problem. Without that snippet code, you lose them. The reason I suggested a list of examples in the guides was as a catch all for all of the code examples we produce to document features and create code snippets for the docs. As just one example (I've done this a bunch over the years), I did this in go_router and it's one of the things that caused go_router to start at #6 on the list of Flutter router solutions, after which is went straight up from there. |
If guides are incomplete, then we should make them complete.
As with any documentation, it's the project's responsibility to keep it from going stale.
This is a significant maintenance burden. Nearly every project that's created will be about 95% identical to all the others, due to files and code that form the basis for all static sites. When and if any changes occur to the baseline implementation, all 20 projects, or 50 projects, or 100 projects will need to be updated. This might be mitigated at some point with code that's written for the purpose of automating such migration. However, no such code currently exists, and it doesn't seem like a great use of early development time to write that code.
Which is why the docs website is accumulating many such snippets of example code. I'd like to push the doc website as far as it can go. It's not as if we've pushed ourselves to the max to create the greatest docs website and then discovered that it can't provide the instruction that we need. We've barely even started the doc website. So I'm not convinced that a large number of standalone projects is currently a necessary tool or investment. At the moment, my interest is very specifically focused on the following:
I believe that through repeated work on specific problems, and specific difficulties solving those problems, we will arrive at the appropriate aides, whether that be website guides, example projects, Dart Docs, and even Dart lint rules. |
|
It's your project, so you're allowed to set the priorities as you see fit. I feel pretty strongly about having these kinds of samples, however, so I'm probably not a good fit as a contributor. |
Just establishing the first example (showing off a custom finisher) and a place in the docs where examples can be listed (just listing the first example for now).