What range of knowledge should we assume in documentation?

[aredridel]

What knowledge drops are we assuming is in-scope vs out?
What are our target people for our documentation and introductory texts?

[grawk]

The current content is accessible for developers who are familiar with MVC frameworks though not necessarily nodejs or JavaScript. Do you have any specific categories in mind to try and rule in or out?

[pvenkatakrishnan]

I think that is debatable @grawk We assume knowledge of node.js and express is my opinion.

[grawk]

If you read the "Getting Started" it doesn't require you know JavaScript or have used expressjs. It does make reference to expressjs, but about anybody who can find the shell and has a text editor can get through the intro and have a working application.

What is debatable though, is whether that is the appropriate assumption to set the tone for the documentation.

[grawk]

Not that this issue really leads to my next statement, but it's about time to reboot the krakenjs website. Or at least start that process.

[aredridel]

I get asked questions on IRC by people who are new to node. In fact, they want a little more hand-holding than Express gives, and Kraken looks attractive to that.

[grawk]

"application developers with MVC but not necessarily nodejs or JavaScript experience" sounds like a good target audience for the immediate landing content. I believe it's already along those lines. We should cultivate that. In addition we should identify advanced topics that require more coverage and make allowance on the website for that as well.

[grawk]

Oh, and maybe we should provide links to more fundamental information as well (learn you JavaScript, learn you node.js)

[aredridel]

Yeah, or at least refer out to other material when we presume knowledge.

[grawk]

do you think there's currently anything missing from the Getting Started towards that end?

[aredridel]

Yeah. All the concepts we assume people know. Middleware, handlers, req, res.

[grawk]

Link to expressjs doc then?

[aredridel]

Yeah, though whether shallowly or deeply is a question -- mostly I think we need to be aware of what knowledge we're assuming, and handle each case

[grawk]

Currently the site is just one long scroll, so it's one size fits all. I like the fact that you can get a working app just by basically following steps and skimming, without any other information. But you and @pvenkatakrishnan are right. There are assumptions made when read more thoroughly. I'd like for there to be the basic "get up and running" tone right up front. But for there to be additional sections on the site that dive more deeply into the topics you mentioned (middleware, handlers, etc) and possibly others.. like i18n? Those sections could link more deeply into expressjs (and other) documentation.

[aredridel]

Yes, definitely! There's a lot of power in getting up and running, then explaining, but we're running into teams that don't know what middleware is, don't really understand a lot of the concepts -- and wouldn't find it from our docs

[grawk]

The site was great for MVP purposes. Sounds like we've got enough insight now to improve it. Probably we don't want to do that planning here in this issue. But we can leave this open until we are sure it's captured wherever/however we plan the new content.

[pvenkatakrishnan]

I got to agree with that @aredridel . Understanding middleware, req/ res lifecycle, i think, will solve majority of the problems in teams

[pvenkatakrishnan]

Not only with understanding how express/kraken works but also with designing their apps.