Replies: 9 comments 8 replies
-
Have a look at the docs repo here: https://github.com/serenity-is/docs This feeds the docs site here: https://serenity.is/docs/ I don't know if the site gets automatically update each time the repo gets a push to main, but you'll find a bunch of content on there! HTH! |
Beta Was this translation helpful? Give feedback.
-
Hi folks, My problem with the docs/samples/tutorials is that they seem to be out of date. I don't see a lot of recent activity on https://github.com/serenity-is/docs and when I run the samples I can't find the referenced source items. For example: Removing Add Button says:
But, when I look in the files, I don't see a RemovingAddButton.ts. When I try to follow the links I get a 404 on GitHub. I also see that the demo page gets the link like this:
... but I don't see where BasicSamplesSourceFile method is defined. Eventually through ObjectBrowser I find it, and I think that instead of return new HtmlString("<a target="blank" style="font-weight: bold;" href="" + helper.Encode("https://github.com/serenity-is/common-features/blob/master/src/" .... The path should probably be something like https://github.com/serenity-is/common-features/blob/master/src/Serenity.Demo.BasicSamples/ and maybe some additional path-parsing info to get to the right place. As you can see, I eventually did find the right file (https://github.com/serenity-is/common-features/blob/master/src/Serenity.Demo.BasicSamples/Modules/Grids/RemovingAddButton/RemovingAddButton.ts) but it took a couple of hours for me to get to the right place because I didn't think of searching for that file name in the git repository, I kept looking for the file within the generated project files. I am trying to evaluate adoption of this framework but am really struggling. |
Beta Was this translation helpful? Give feedback.
-
PS: Once I get to the right .ts file, I think something else is still wrong:
... I attempted to do this, because the generated file had a similar statement for Decorators, but I couldn't get it to work:
... I can get an explicitly qualified reference work, like this:
... indexOf isn't available, and I'm not sure exactly how to qualify or import to get this to work as shown. The source file hasan import from "@serenity-is/corelib/q" but I couldn't hit on the right thing to use. I ended up dropping back to the "not recommended" explicit index removal statement, because it works:
... I think there is some serious versionitis going on here and I am probably just in the wrong branch or the wrong .ts file altogether, but I can't find the right one. If it matters, and it probably does, I downloaded Serene.Template.vsix on 11/3. In Visual Studio 2022, everything is patched/updated. NPM -v returns 8.1.2, node -v returns v16.13.2. C :\Program Files\nodejs (verified location on my box) moved to the top of the tools list. The welcome page says "Also .NET 5 SDK for VS needs to be installed from https://dotnet.microsoft.com/download/visual-studio-sdks" but there isn't anything labelled .NET 5 on that page. I don't see it in the "Individual Components" page when looking to see if I have missed something either. There is something labeled ".NET SDK" with no version number, which is installed. Also .NET Framework 4.8 SDK is installed. MS documentation says .NET 5.0 (SDK and runtime) is end of life. Other than the .NET 5.0 thing, I followed the instructions in https://serenity.is/docs/getting_started/installing_serene_from_visual_studio_gallery.md as far as I can tell, except that the images show the premium template. No idea what I am doing wrong. I do see that I get a warning (just one!) when I build, which says:
... so clearly something is slightly out of synch, but it shouldn't be this messed up, should it? I am going to stop until I hear from somebody clarifying how this is supposed to work. I wanted to do a simple mod and then evaluate exception handling -- I've completely failed so far to see how the logger is invoked, at least for a javascript error -- but am getting too frustrated to continue. |
Beta Was this translation helpful? Give feedback.
-
Hello, I see there is some confusion about the Namespaced and ESM version of the script. We are working on switching to ES Modules. And both of the versions are supported at the same time. Check the blog post about switching to ES Modules https://serenity.is/blog/2022/10/15/switching-to-es-modules The demo code it has already converted to the ESM and the documents are still having examples with Namespaced typescript. The documents will be updated after the switching seems okay. You can easily clone the serene repo with submodules and checkout the previous version of the samples to see the Namespaced code version. Or you can update your project to use ESM and check the updated samples from the serene template repository. The transformations take time, and we are still facing some custom case issues which needs to be resolved. This is an OpenSource project. You are welcome to open pull request to the public projects at any time. After a review of the code, if we didn't have a major change in the source code which can affect your pull request, it will be merged. And the documents are also open for PR's. Please note it, we have a premium version of serene which is name "StartSharp", you cannot open pull request to the OpenSource version with our private repository code due to license restrictions. There are repositories which are public, and you can open pull request: |
Beta Was this translation helpful? Give feedback.
-
Ah, I see now! Thank you Pete. I have liked helping developers throughout my career, and I like writing, so I’m with you on this. If I follow through on Serenity, maybe we could come up with a good crowdsourcing mechanism for the docs together. I do see a “Wiki Contribution Guide” and there is a lot there although it’s kind of disorganized. I think the first thing I would do is add a new page linked to the home page that provides some sort of organized table of contents by category, or an index, to the existing wiki pages.
L<
Lisa Slater Nicholls
From: Pete Reeves ***@***.***>
Sent: Wednesday, November 9, 2022 1:47 AM
To: serenity-is/Serenity ***@***.***>
Cc: LSNicholls ***@***.***>; Comment ***@***.***>
Subject: Re: [serenity-is/Serenity] Is there a hidden documentation site? (Discussion #6253)
You can see all the things that end up in Q under devtools
<https://user-images.githubusercontent.com/93528617/200795533-427ca082-1ef1-415c-bef0-e3d91fc3ce40.png>
I don't know much about importing so I can't answer that.
I've been using the framework for years and love it very much, I'd also be happy to contribute to docs if there was an easy way to crowdsource it as I'm often walking devs through the basics and what's changed recently. I have the advantage now of dozens of old projects where I've solved problems or come up with a technique to get it done real quick. I like to try helping people out to support the project these days.
—
Reply to this email directly, view it on GitHub <#6253 (reply in thread)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AVASPTHEWZD6R274ZQ4NAVDWHNXKPANCNFSM5NK23MZQ> .
You are receiving this because you commented. <https://github.com/notifications/beacon/AVASPTB5773MVFXR5DVSRFLWHNXKPA5CNFSM5NK23MZ2YY3PNVWWK3TUL52HS4DFWFCGS43DOVZXG2LPNZBW63LNMVXHJKTDN5WW2ZLOORPWSZGOAA7H2KQ.gif> Message ID: ***@***.*** ***@***.***> >
|
Beta Was this translation helpful? Give feedback.
-
Thank you very much Victor!
L<
Lisa Slater Nicholls
From: Victor Tomaili ***@***.***>
Sent: Wednesday, November 9, 2022 2:36 AM
To: serenity-is/Serenity ***@***.***>
Cc: LSNicholls ***@***.***>; Comment ***@***.***>
Subject: Re: [serenity-is/Serenity] Is there a hidden documentation site? (Discussion #6253)
The demo is updated to fix the links to the samples.
https://serenity.is/demo/
—
Reply to this email directly, view it on GitHub <#6253 (reply in thread)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AVASPTDOCQMCFFXHDA2CWLDWHN47XANCNFSM5NK23MZQ> .
You are receiving this because you commented. <https://github.com/notifications/beacon/AVASPTHRX6SSQCBB5XASDH3WHN47XA5CNFSM5NK23MZ2YY3PNVWWK3TUL52HS4DFWFCGS43DOVZXG2LPNZBW63LNMVXHJKTDN5WW2ZLOORPWSZGOAA7H5FI.gif> Message ID: ***@***.*** ***@***.***> >
|
Beta Was this translation helpful? Give feedback.
-
Thank you Edward – I agree about the need for planning.
And I can attest to the fact that the doc organization issues are not limited to Serenity, so I’m not blaming anybody at all! It is a natural problem.
There is besides the wiki and the docs, the blog (I understand why the blog should remain separate, it’s just hard to cross-index everything you need to know when you’re starting out). There are also useful bits in https://github.com/serenity-is/Serenity/discussions and on https://stackoverflow.com/questions/tagged/serenity-platform , that need to be expanded and promoted into the docs (or, more likely, the wiki) in a meaningful way.
On the “official” docs side, I would also say that the wonderful samples need to be connected in the docs in a different way than they are. For example, maybe the How-To Guides in Knowledge Base section of Serenity Guide could be expanded, with an article that links directly to each sample, and with the existing How-To Guide items also connected to samples wherever feasible. Right now, the existing How-To Guide items look like they are just a second-generation version of the FAQs, better organized and separated out for length. And at least one of the FAQs is really a Troubleshooting item, I think.
Now that I think about it, the FAQs is possibly a good place to serve as the overall index to “How can I find out about….” rather than just listing individual questions in an unstructured way. Just a thought.
At this point I only have newbie problems that are highlighting the doc organization issues, and not any expertise to contribute to the community portion(s) of the docs. I hope that will change. But I *do* have considerable editing and documenting experience and I would be happy to put it to use here if I continue with Serenity.
To your point about offering concrete incentives, I personally would vote against them for the reason you state but also because it leads to counter-productive competitiveness and a lot of less-than-useful content. Ask me how I know <g>.
I’m glad some core platform users are aligned with this general idea, and now you can step back and take your time, so the project organizers can weigh in with what they would like to see as both a process for crowd-sourcing this work and an overall plan for what the results would ideally look like.
L<
Lisa Slater Nicholls
From: Edward ***@***.***>
Sent: Wednesday, November 9, 2022 12:51 PM
To: serenity-is/Serenity ***@***.***>
Cc: LSNicholls ***@***.***>; Comment ***@***.***>
Subject: Re: [serenity-is/Serenity] Is there a hidden documentation site? (Discussion #6253)
I would be happy to contribute, too. It would be worth planning this out a bit before diving straight in, so we know what we're in for and so we don't land up fragmenting it.
The wiki consists mostly of community entries, whereas the /docs is more of an official guide.
Community entries typically only get updated by the original contributor, so I guess easy for them to get a bit stale.
* Some of them are redundant because they have been incorporated into the framework itself, or into the Serene template.
* Some of them are probably worth bringing into the official docs
* How would we manage the rest (also preventing them from becoming stale)
In terms of the official docs, they're generally good, and recently there have been loads of updates to the framework - especially to the ES modules as Victor mentioned above. The team has pushed the updates into the pro template (StartSharp) to make sure any issues are ironed out first on a smaller set of users, and during/after that, I have no doubt the docs will be updated too.
This said, I agree with some of the points raised, and would like to get some of our heads together on how we can improve the docs & guides to this really fantastic framework. We could offer some kind of bounty in the form of "internet points" or have things paid-for (I can offer to contribute here too). Only thing to be cautious of is de-incentivising the folks who do things out of goodwill.
@volkanceylan <https://github.com/volkanceylan> or @VictorTomaili <https://github.com/VictorTomaili> do you guys have thoughts on this? Happy to start a new thread or discussion to start bouncing some ideas - or contact me privately if you like.
Thanks again for the very hard work - I wish there was more I could do to help!
Cheers,
Edward
—
Reply to this email directly, view it on GitHub <#6253 (reply in thread)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AVASPTEBXDUZRRPIKTQ4H7LWHQFDJANCNFSM5NK23MZQ> .
You are receiving this because you commented. <https://github.com/notifications/beacon/AVASPTASCZLIRWT4H3SRBD3WHQFDJA5CNFSM5NK23MZ2YY3PNVWWK3TUL52HS4DFWFCGS43DOVZXG2LPNZBW63LNMVXHJKTDN5WW2ZLOORPWSZGOAA7JIUA.gif> Message ID: ***@***.*** ***@***.***> >
|
Beta Was this translation helpful? Give feedback.
-
So okay, @edwardch and everybody, it took me longer to get to sit down and write this than I intended, but here is what I think might be useful and workable if people wanted to collaborate. https://github.com/serenity-is/Serenity/wiki/A-proposal-for-%22dogfooding%22-Serenity-documentation |
Beta Was this translation helpful? Give feedback.
-
No apologies necessary, @edwardch . Please take your time and good luck with your upgrade! I am in UAT with my first Serenity application right now and very happy to have my own app documentation in place :-). Revising it constantly of course, but only the app-specific topics, not the sample ones I supplied in the proposal. The users like having it, too. So I hope it is a worthy module-contribution to the Serenity eco-system, even if nobody agrees with me that developer documentation could be managed this way! |
Beta Was this translation helpful? Give feedback.
-
I struggle to find what's available in Serenity, and even methods or classes that exist and are utilized in my project, I see no mention in any documentation. Is there a docs site with just poor SEO so I can't ever find it, or is the current state of the documentation all we have?
If its the latter, could anyone clue me in to how you manage to get by without wasting hours in hoping you're on the right path?
Beta Was this translation helpful? Give feedback.
All reactions