Open grokys opened 6 years ago
daveaglick
commented
6 years ago Definitely interested in making the docs and onboarding process better. Any suggestions on how to improve it? Maybe a “Getting Started” page (or section) with first-principles?
grokys
commented
6 years ago Hi Dave,
Yes I think a "Getting Started" page or section would be invaluable. Here's a few things that come to mind that I was/am struggling to understand, or I had to search around a bit too much to find:
As a jumping off point, I also think the jekyll docs are a decent place to start when it comes to guiding a new user though getting started.
onnotasler
commented
6 years ago That is true, I struggled a lot when I tried to figure out how Wyam works. I still do not know what NuGet might be good for, but it seems to work without me knowing that.
If I were to rewrite the documentation, I would start with: 1) What is Wyam and why should I use it? 2) How to obtain and install Wyam? What are the differences and which chould I choose if I do not understand any of them? 3) How to configure Wyam, including an explanation what format the file expects (for example, "put a Settings[""] around the option you want to include"). 4) How to run Wyam. 5) My first page in Wyam: Blog, Book, Documentation. Then, branching from 5 into the more details, as detailed by grokys above.
daveaglick
commented
6 years ago This is all really excellent feedback, thanks! I’ll try to carve some time in the near future to do another round of docs improvements.
awulkan
commented
6 years ago It was a while since I last tried Wyam (been quite busy the past 6 months or so), but here's some feedback from me.
I think the main confusion on my part when I first tried Wyam was that I didn't get a local copy of the actual theme files when I created my blog. So I had no control over it.
Most static generators give you all theme files in a theme folder when you init a new site. But instead I had to go to Github, look through the repo, and manually download a zip file for the specific theme. Then I had to figure out how to make Wyam use those files instead of the default ones. Not a pleasant first experience. Maybe this could be solved somehow by allowing a theme to be downloaded through a CLI command?
Also, as @grokys said, the docs pretty much only contain very low-level info. Most users need to know how to build a custom site from start to finish, and they need to be hand-held through that process. Whether it's by using a pre-made recipe and just building a theme for it, or if they need to create a custom pipeline (never figured this part out before I had to put Wyam to the side) to make their site work as they want.
When I read about Wyam on various sites I constantly see mentions of the powerful and flexible pipelines and so on, but when I look at actual sites built with Wyam they almost always use the default recipies and themes, as far as I have seen. Is this because people can't be bothered creating something unique, or is it because they don't know how to do it?
Anyway, these were just my initial thoughts when testing Wyam. Maybe it has changed a lot since back then. I am going to give Wyam another try in a couple of months, or when it's running on .NET Core. If I only knew how to actually use Wyam myself I'd be happy to help writing a get-started guide for it. But last time I tried to figure out how to do anything with the pipeline I was left dumbfounded (maybe I'm just stupid).
On another note, great work so far, I see that you're committing a lot of stuff to make Wyam work with .NET Core. I'll continue following this project and cheer you on!
daveaglick
commented
6 years ago @AWulkan Thanks a bunch - that’s all really great feedback.
There’s an issue in here somewhere for adding a command to download and unpack a theme directly from the CLI. It’s probably about time to take another look at that one after the .NET Core port is complete.
awulkan
commented
6 years ago @daveaglick No problem. Yes I think that issue was created a long time ago when we discussed it on gitter.
https://github.com/Wyamio/Wyam/issues/349
I've been waiting since 2016 for that feature, haha. No need to hurry though, .NET Core is more important.
niqhtei
commented
6 years ago +1 from me about docs. Mainly the reason I had to use something else for my documentation (didnt have much time to play around and had to get something done quickly).
As for themes, I like how docfx lets you export a theme into local folder. Then theres a documented config property how to use it instead of default.
As for everything else, it felt like I had to go through the source code of Wyam to figure out how things actually work. The main issue was I couldnt understand what were the inputs and outputs. Docs talk about IDocument, but what is it really? Where does the metadata come in? What is the actual Razor template's model? Default Docs recipe wasnt enough for me so I wanted something a little bit custom, spent a bunch of time going through the source code, cause I couldnt get a grip of what the actual data model for each document was.
By the way, a question: If something heavily customized has to be built, should I build my own recipe? Whats the story with debugging then?
Oh this made me remember, didnt find anywhere in the docs if it's possible to register my own recipe, and how to do that.
daveaglick
commented
6 years ago @bitfringe With regards to your question about custom recipes - end users should almost never need to build a custom recipe. I've gotten this question several times before and I think it's another area where the documentation could be greatly improved. A recipe is a custom configuration that has been generalized and is intended to be distributed and used by multiple end users for a given use case. They are currently delivered as NuGet packages with a class that implements a particular interface (which is found via reflection).
What you almost certainly want to do is create a custom configuration in your "config.wyam" file by adding pipelines and modules. That is expected and encouraged for end users as not all sites are going to fall into the predefined scope of the existing recipes like blog and docs.
You also asked about debugging: it's not currently possible to debug a custom configuration inside a "config.wyam" file (though it's theoretically possible to add this in the future by generating a PDB file of the configuration file). That said, I know some folks have taken to writing their custom configuration inside a compiled assembly and calling that from the configuration file, which would look something like:
#a MyConfig.dll
MyConfig.Configure(this);That would be debuggable by using the --attach CLI flag to pause execution and then attaching a debugger to the Wyam process.
awulkan
commented
6 years ago @daveaglick Maybe I'm going a bit off-top here but I have a question.
When I read about the blog recipe it felt kinda restricting. I need to follow a specific folder/file structure, I get a specific set of features, etc. What if I wanted to have a custom folder structure or features that might not be supported by the blog recipe? Is this something that can be modified easily, or is it outside of the scope of Wyam? Would I need to create a custom recipe just to have my folders structured differently?
daveaglick
commented
6 years ago @AWulkan Your question is definitely related to the question about recipes vs. custom configurations. That kind of customization certainly isn't out of scope for Wyam - the whole point of Wyam is to be highly customizable.
That said, it may be out of scope for a particular recipe. The recipes can only go so far in terms of what they'll support - it's a balance between providing customization options without making the recipe too complicated. Once it reaches a certain complexity the recommendation is to go custom config. Attempting to do deep customization to a recipe that doesn't have built-in support for a particular change (like a setting) can get tricky.
I think there's probably a documentation problem here in that because we have recipes the thinking is that custom configs are for "experts" or limited to "advanced" use cases. That's not the case at all. Custom configuration was intended to be the backbone of Wyam from the beginning - very similar to the philosophy behind Metalsmith. If they seem too complicated then that's on the documentation for not making them clearer.
niqhtei
commented
6 years ago I'd definitely be interested in doing my own custom recipe. Or somehow running this custom "config" in separate assembly so I can get tooling, cause that wouldnt be a simple config.
fmonroe
commented
6 years ago I would like to add (fairly newbie point of view): I struggled for days trying to get Jekyll working (on Windows); I barely got Hexo working; now I just found Wyam through Miroslav Popovic's blog and, just like him, I prefer a .NET based platform. After reading the documentation (newbies do read the documentation because we don't want to bother the authors with stupid questions), I need to voice my agreement with the original post: IMHO Wyam would benefit from a better 'Getting started' documentation. I offer my help.
In the meantime how is it that I get help? I do not see a forum on the wyam site. Do I open an issue here? My question probably has been already answered many times in issues that are now closed?! How do I search for it? Do I ask questions in the Gitter room? Again the same question probably has been asked tens of times and Gitter is not searchable (that I know of). Please let me know the proper, efficient procedure to get help. Please do not read anything negative into my comment - this is very good product and I want to use it for my static sites. Thanks and Congrats Dave for the good work.
awulkan
commented
6 years ago @fmonroe Just leaving an answer until Dave get here. I think Gitter is the best alternative. You can actually search in Gitter, but since the new design arrived it became a pretty terrible experience. As you can see in this screenshot there's a section in the search panel called "CHAT MESSAGES", that's where the results end up (you need to be in the Wyam channel first). https://i.imgur.com/AsoLNUb.png
Another way would maybe be to contact Dave on Twitter? https://twitter.com/wyamio I don't know if it's a good place to get help on though.
SilentSin
commented
6 years ago If I were to rewrite the documentation, I would start with: What is Wyam and why should I use it?
To expand on this point a bit more, I (as a new user to Wyam and with no web development experience) want a high level overview of what I put in and what I get out. Something along the lines of:
Hey all!
You're probably already aware of all this, but it's rather difficult to get started with Wyam with the current documentation.
For example, I go to the docs and the first page is "Documents". A good first page, but what I would expect would be something like:
Instead the page seems to be a low-level explanation of how documents are processed by Wyam, with no context for this information.
In general the whole of the documentation seems to follow this pattern, making it very hard to get started. I know how difficult documentation is (we've started using Wyam because our documentation for https://github.com/AvaloniaUI/AvaloniaVS sucks even more ;) ) but just thought I'd record my thoughts here.
Thanks for all your work on Wyam!