This project needs documentation

[arechsteiner]

I've been looking for something like Pretzel that runs on .NET, but the lack of documentation and tutorials make it very, very hard to start using it.

I haven't used Jekyll or anything like it before, so I'm really just trying to figure it out using trial/error (which isn't ideal as you'd imagine).

[sriv]

@arechsteiner - I have been using Pretzel for a while, but then I am fairly conversant with markdown, and jekyll (at least for my needs).

I recommend that you look at MarkPad, it is a neat editor for creating pages in Markdown syntax, and even lets you build on a Jekyll template.

As for Pretzel, I feel the beauty is in it's simplicity - This wiki was all I needed to know about it :).

But, if you have specific areas where documentation can help, please elaborate.

[kindohm]

@arechsteiner what are you having difficulty with? building and running Pretzel? Liquid tags? Custom page creation? I'd be willing to help build up the documentation, but it would be helpful to know specifically what docs are most needed.

[arechsteiner]

@sriv. @kindohm: Basically there needs to be a tutorial on how to create a site with Pretzel, what all the files in a Pretzel project are and how they are used to form the static HTML output. Also how to use all commands with all the possible options. I've been trying to figure out what template languages are supported by create -t but I couldn't find anything.

Just imagine someone who knows how to build sites with HTML,CSS and JS but hasn't worked with a static site generator before. How would you introduce and enable them to use Pretzel? How would you explain Pretzel to them so they can use it without looking at the source code, or Googling how Jekyll works?

Obviously, you could make references to Liquid and Markdown tutorials for learning those. It's more about how the tool works, which files will create what. What are posts? What are layouts? How do I create an aboutme.html on the same level as index.html? How do I create a post?

I'm currently figuring all of this out simply by looking at the file structure and trying out stuff. I'm sure this is a hurdle for a lot of users.

[JakeGinnivan]

Part of the reason we chose to support the Jekyll conventions are so we didn't have to reproduce the same doco.

Once you understand how Jekyll works (which is well documented) pretzel is pretty simple. Agreed on the templates, it should print that out with the command line help.

Sent from my Windows Phone

---

From: Alexander Rechsteinermailto:notifications@github.com Sent: ý3/ý05/ý2013 0:22 To: Code52/pretzelmailto:pretzel@noreply.github.com Subject: Re: [pretzel] This project needs documentation (#141)

@srivhttps://github.com/sriv. @kindohmhttps://github.com/kindohm: Basically there needs to be a tutorial on how to create a site with Pretzel, what all the files in a Pretzel project are and how they are used to form the static HTML output. Also how to use all commands with all the possible options. I've been trying to figure out what template languages are supported by create -t but I couldn't find anything.

Just imagine someone who knows how to build sites with HTML,CSS and JS but hasn't worked with a static site generator before. How would you introduce and enable them to use Pretzel? How would you explain Pretzel to them so they can use it without looking at the source code, or Googling how Jekyll works?

Obviously, you could make references to Liquid and Markdown tutorials for learning those. It's more about how the tool works, which files will create what. What are posts? What are layouts? How do I create an aboutme.html on the same level as index.html? How do I create a post?

I'm currently figuring all of this out simply by looking at the file structure and trying out stuff. I'm sure this is a hurdle for a lot of users.

— Reply to this email directly or view it on GitHubhttps://github.com/Code52/pretzel/issues/141#issuecomment-17348265.

[arechsteiner]

@JakeGinnivan: In that case it would be helpful to state this fact in the read-me of this project. Otherwise, how will a new user know he has to read the Jekyll doc to understand Pretzel, and that it actually applies?

[JakeGinnivan]

@arechsteiner fail point.

I have updated the Readme to include a link to the Jekyll getting started page which outlines conventions and such. https://github.com/Code52/pretzel/commit/6fd600461d9f8208b0fd73cb7370c20e21692d18

Cheers! Jake

[rnorbauer]

Hi all,

I'd like to write a beginner's tutorial on pretzel, but I would need some help from people more familiar with the code base.

In particular, docs are needed for things that don't map directly to Jekyll.

For example: -Azure deployment -Razor templates, etc. -LESS templates

Anybody want to help? Mostly being available to answer some questions from me by email would all that would be required as I poke around through the source and try to understand it.

Ryan

[JakeGinnivan]

Sure

jake at ginnivan dot net

[rnorbauer]

Awesome. Thanks, Jake. I'll dig around in the source for a while and then e-mail you a list of questions of stuff that isn't obvious to me. My ideas is try to flesh out the wiki a bit first, and then I'll write up a more informal tutorial somewhere that is more of a walk-through with commentary of how to make and deploy a Pretzel site, and how to migrate an existing Jekyll site.

I currently have a pretty large and complicated Jekyll set up that I'm using to generate my site, so I think it'll be instructive for discovering edge cases. I look forward to moving that over to Pretzel and making some improvements along the way.

[laedit]

@rnorbauer if you still want to contribute to the docs, we can use Jabber to discuss.