Could you provide a user guide/book?

[ScottHuangZL]

I am use Yii1 and Yii2 (a famous PHP framework) for web developing, it provide quite useful user guide and books for users to ramp up. And Yii provide a very handy widgets to build web quickly. Integrate Jquery 2/Bootstrap 3

1. I am currently self study Rust-Nickel by interesting. Could you provide a handy books for users to ramp up for Nickel framework?
2. Do Nickel plan introduce module/widgets and so on? May be some pre-build macro?

Thanks.

[Ryman]

1. Can you provide links to the guides you're referencing? I don't think there's any active effort on this but it's definitely something for which interest exists. Can we determine what a minimally viable guide is? A simple blog?
2. My knowledge of front-end is rather dated, perhaps @cburgdorf can chime in on this? (It sounds like this is out of scope for nickel, but it could be built on top?)

[ScottHuangZL]

The better way to become a popular web framework is to provide better DOC and better user friendly web UI:) You can deep dive into PHP Yii2 framework to get some hints.

Or,at least provide competitive tools like beego(one web framework write in GO by a Chinese guy). Thanks.

[cburgdorf]

Hi @ScottHuangZL,

thank you for your feedback and interest in Nickel. Regarding the website and the documentation/guide. You are absolutely right. We need to do better here. It's on my to do list to jump in here together with @PascalPrecht to improve the situation. I recently wrote a blog post about writing your first nickel application and deploying it to heroku:

http://blog.thoughtram.io/rust/2015/07/29/a-web-app-with-nickel-from-first-line-to-heroku-deployment.html

I'll have more time to work on the project soon. Better documentation and guide is coming! Trust me ;)

Do Nickel plan introduce module/widgets and so on

To be honest. I don't see us doing that any time soon. My personal vision for nickel is more to be a lightweight middleware oriented framework rather than a fully fledged MVC inspired kind of thing (or even something that goes beyond that). That said, you could totally build something on top of Nickel to provide such modules as part of a bigger community driven Nickel ecosystem.

[cburgdorf]

I just wanted to let everyone know that I kicked off work for a developer guide in a Google Doc

https://docs.google.com/document/d/1gArtjOoovBV5lB7Cztyz4Du6GeCtD9ri44PrGuHrwSE/edit?usp=sharing

This is inspired by the Angular project where we also first draft chapters in a Google Doc so that multiple people can write in one document at the same time. It's also easier to review so that we basically have a faster feedback cycle. At the end we will just turn that into a nice website. Let's first focus on getting the content right.

For now, I first want to get a basic outline ready and then we can dive into writing the chapters. The current state of the document is just what I came up with within the last minute ;)

Anyone who wants write access to the document please let me know your email :)

[Ryman]

@cburgdorf Perhaps we could use https://poetica.com/github on a 'guide' repo, or https://etherpad.mozilla.org/?

[cburgdorf]

Poetica sounds interesting but I couldn't get it to work 😳 Etherpad looks pretty dated. Google Docs works really well for uns in the Angular project. Do you have any specific reservations against it?

[ScottHuangZL]

Unfortunately, I am in China and cannot access to the google doc. How about use gitbook or other online DOCs, thanks.

[cburgdorf]

@ScottHuangZL Ah, that sucks. I'd like to have something just for drafting that allows multiple users to simultaneously work on one document. But I definitely don't want to exclude people from China so I'll investigate what other options we have. Poetica sounds actually promising.

[cburgdorf]

I just played with poetica but some missing formatting features already drive me nuts ;)

https://poetica.com/drafts/613fb858ebe02a13fd20636e

[cburgdorf]

Also tried out hackpad

https://hackpad.com/Developer-Guide-xKWj6bxZ4cI

Formatting is a little better than with poetica but commenting doesn't seem to work that well. Not sure about the collaborating features.

[Ryman]

Looks like hackpad requires signin just to add comments :/

What are the formatting features are you worried about? Something out of the scope of markdown? (I didn't consider formatting being a big deal for draft documents)

[cburgdorf]

Well, for instance I couldn't figure out how you indent a list to a 2nd or 3rd level. For now I just used - to manually achieve that but then the line spacing is very tall which makes the whole document less readable.

[cburgdorf]

I just noticed the markdown mode but it seems buggy. For instance try to create such a list.

• test
• test
  • second level
  • second level
  • third level
  • third level

When you go into preview mode it looks correct but in the normal writing mode the indentation is messed up.

[Ryman]

shrug

I tried to import the changelog to see how nested lists look and now everything is broken and I can't read anything. I think this unilaterally proves that signing into things breaks things :skull:

[cburgdorf]

I tried to import the changelog to see how nested lists look and now everything is broken

You mean at hackpad or Poetica?

I looked at many different options but couldn't find anything quite as good as Google Docs. However, I'm ok with trying out Poetica for now. I can adjust my zoom level to 75 % or just use some custom css to get rid of the overly huge font and spacing ;)

For the nested lists we can use tabbed hyphenation. It's a draft after all ;)

[ScottHuangZL]

@cburgdorf Usually the key book/guidance is create by the owner/key developers themselves.

You can use your preferred writing tool to create DOC, just need publish the PDF version and Online version to reflect the key concept and guide your followers to easily leverage to create web by Nickel effectively and efficiently.

Thanks.

[ScottHuangZL]

Could you compare Nickel & Iron? thanks.

[flosse]

Could you compare Nickel & Iron? thanks.

This could be a starting point: https://github.com/flosse/rust-web-framework-comparison

[cburgdorf]

@flosse I noticed that a while ago. Great writeup. Would you be interesting to collaborate on a dev guide with us?

[flosse]

Would you be interesting to collaborate on a dev guide with us?

yes, I am :) But there are two things you should know:

1. my English isn't great
2. I'm quite busy

Nevertheless, I'll see where I can help.

[flosse]

I'd prefer a "rusty" open source solution for our guide, e.g. mdBook could be a solution.

[cburgdorf]

1. my English isn't great
2. I'm quite busy

We are in the same boat here ;)

I'd prefer a "rusty" open source solution for our guide, e.g. mdBook could be a solution.

I fully agree. I just like to have something more collaborative for the drafting process. We use Google Docs for the Angular project to draft the developer guide and it works out quite well because

• multiple people can simultaneously write in one document
  • -> easier to collaborate
  • -> also leads to a super fast feedback loop
• commenting on text blocks works well
  • -> which also contributes to a fast feedback loop

The content is the most important part for the guide so crafting the content should be as frictionless as possible. Once it's done it should be easy to use something like mdBook to put it into a nice form :)

[SimonTeixidor]

I'm thinking that a good approach to a guide might be to create a web application, and document each step in some sort of tutorial. See Miguel Grinberg's tutorial on Flask for what I consider to be an excellent tutorial for beginners. This approach would also give us a nice example project for Nickel.

Do you guys think this is a good idea? I'm thinking an image gallery or something (or a blog of course, but everyone seems to be doing that, so it could be fun with something else for a change) could be a good project maybe.

[flosse]

I'm thinking that a good approach to a guide might be to create a web application, and document each step in some sort of tutorial.

I really like that idea!

I'm thinking an image gallery or something (or a blog of course, but everyone seems to be doing that, so it could be fun with something else for a change) could be a good project maybe.

hmm... I guess the type of project really influences the guide. A REST-API-Server in Rust might have other emphases as a CMS with server-side rendering. Do you use nickel in a real-world project? If so, what kind of project is it?

[SimonTeixidor]

hmm... I guess the type of project really influences the guide. A REST-API-Server in Rust might have other emphases as a CMS with server-side rendering.

We could have both. An image gallery (or a blog, for that matter) can have a REST API that could potentially be used from mobile apps and such.

Do you use nickel in a real-world project? If so, what kind of project is it?

No, but I've actually been meaning to write an image gallery for hosting pictures to people on my network. It occurred to me that such a project might make a good tutorial, so I suggested it here.

[flosse]

We could have both.

you're right

So let's start to build a gallery that supports simple blogging and commenting :)

[flosse]

For the drafting process I'd prefer a open solution with no sign-up requirements or accounts. I'm totally fine with a simple textfile like etherpad or a gist.

[cburgdorf]

@flosse do you have a recommendation for a hosted etherpad. https://beta.etherpad.org/ looks much nicer than https://etherpad.mozilla.org/ but it says it frequently destroys the pads as it's only meant for testing.

I'm happy to use an open source solution as long as it's convenient enough to use for the drafting process. It should allow comments on text blocks, it should allow multiple people to work at the document at once and some basic formatting features would be nice.

I just pasted the work in progress outline into beta.etherpad.org and it looks quite good. https://beta.etherpad.org/p/nickel-guide-draft (not sure how long the link will work though)

On the otherhand etherpad.mozilla.org seems to lack basic formatting features: https://etherpad.mozilla.org/3Ekp6MscVB (notice the missing headings)

Also I wasn't able to make comments there.

[cburgdorf]

Regarding the demo app. I'd love to see us coming up with a good demo show case that can lead through the guide. How do want to handle persistency? I wouldn't want users to be forced to install a database on their machine to follow the tutorial. We could probably use the repository pattern and come up with a simple file based storage but there may be other modern alternatives, too (e.g. firebase?) Just throwing this in here.

[SimonTeixidor]

Regarding the demo app. I'd love to see us coming up with a good demo show case that can lead through the guide. How do want to handle persistency? I wouldn't want users to be forced to install a database on their machine to follow the tutorial. We could probably use the repository pattern and come up with a simple file based storage but there may be other modern alternatives, too (e.g. firebase?) Just throwing this in here.

I figured that we could use SQLite as it requires minimal configuration. Now that you mention it though, I realise that not everyone runs a *NIX with SQLite easily installable from a package manager.

Further more, it might be a good idea to keep this project simple. Both for the sake of us actually finding the time to finish it but also for it not to overwhelm a new Rust programmer.

Basic file storage sounds good to me. I'll create a repo for this project where we can discuss the specifics of the implementation.

[flosse]

I figured that we could use SQLite as it requires minimal configuration. Now that you mention it though, I realise that not everyone runs a *NIX with SQLite easily installable from a package manager.

I agree. In addition I think our goal is not teach SQL ;-)

Basic file storage sounds good to me.

I assume, that we'll have some JSON structures so we could use rust-json-file-store (I'll publish it at the weekend soon, it's similar to json-file-store). The current API looks like this:

extern crate jfs;
// ....
use jfs::Store;
//...
fn main() {
  //...
  let data = MyData{ foo:7, bar:"baz".to_string() };
  let store = Store::new(path::Path::new("./data")).unwrap();
  let id = store.save(&data).unwrap();
  let x: MyData = store.get(id).unwrap();
  // ...
}

So there is absolutely no setup required, no dependency except rustc_serialize and all data can be viewed with a editor :) If we'd get bored, we can add a chapter that explains how to migrate to a real database. But since this topic is not related to nickel, it might be the wrong place.

@flosse do you have a recommendation for a hosted etherpad.

No. I don't really don't care, since we'll use it only for a few weeks. I don't want to loose time because of looking for a perfect solution that well be thrown away after a few weeks. I just don't want to create a google/whatever account. Actually I think a github gist would do the job. But choos a tool YOU like and I'll be ok ;-)