Find a good structure

[christianalfoni]

Well made wikis:

http://www.quora.com/What-are-some-examples-of-very-well-made-GitHub-wiki-pages-for-open-source-projects

[christianalfoni]

Okay, I have created a layout suggestion. My thought process:

• Pages sidebar sucks. You can not give a nice menu structure
• Sidebar rules. You can give a very nice menu structure
• Add pages with long names, as they will become searchable in the pages widget
• Custom menu structure in sidebar with short titles, to easily find your way
• The pages widget seems to be closed by default when using a sidebar? That is good :-)

What do you think?

[bebraw]

The current structure (category -> subcategory -> qa) looks ok. If/when navigation becomes an issue, something can be done about it. Architecturally speaking a system could look like this:

• The wiki would be for edits (not discovery) like now. You can of course browse through it but that's not the point.
• There would be a companion site that would get generated based on the wiki content (data structure below)

{
    "category": "Basics",
    "subcategory": "Getting started",
    "title": "How to install Webpack?",
    "content": "Do this and that...\n"
}

In addition there would be a search index for the frontend. See lunr for an example.

The discovery portion would then operate based on this data. You could for instance filter based on category or try more explicit searches (target title etc.).

Technically this isn't a big feat. I've done something similar with jswiki. The site content is generated based on the wiki using ghw, a custom tool I wrote. In this case a tool would parse through wiki pages and emit JSON.

The frontend would then operate based on that JSON and a search index generated based on it. I think a light frontend based on React could work. In addition it would require a router (likely react-router).

Even something light such as riot could work. Given it's brand new technology I haven't used it yet (released yesterday) but it might fit the bill perhaps.

[christianalfoni]

This sounds awesome :-)

Suggest we use the sidebar as a temporary navigation tool for the wiki. When we have content and feedback on its usefulness we can move it to what you describe?

[christianalfoni]

Great work done on JSWiki btw!

[bebraw]

Yeah, the sidebar can remain there. No problems with that.

[bebraw]

I did a first pass at the site. See the main repo for further info.

I think this sort of search fits better QA format. Now some matches tend to be quite big since it matches against title and content. Maybe the articles should have some metadata (ie. tags) attached to them? Then you could search against those and skip having to index content. The tags can be set up by using some convention. Ie. something like this would work:

TAGS: umd, webpack, configuration

It would be possible to parse those using marked quite easily.

[bebraw]

There's a live demo at http://christianalfoni.github.io/react-webpack-cookbook/ now.

[bebraw]

Just started thinking... Maybe the nicest thing to do would be just to run the content through gitbook? I did this with Survive JS and it worked quite nicely.

[christianalfoni]

Hi @bebraw, sorry for late response, I have been away on vacation for a few days.

I really liked the gitbook presentation. How does that work in regards of creating and publishing content?

The search was also cool, though yeah, that is more for Q&A. Is it possible to point it to specific pages?

I will keep adding content until we land a platform, but :+1: on gitbook :-)

[bebraw]

Hi @bebraw, sorry for late response, I have been away on vacation for a few days.

No probs. I did some cleanup and added some new content. There are still blank pages, though. I hope you can look into those at some point.

I really liked the gitbook presentation. How does that work in regards of creating and publishing content?

It is quite straight-forward to set up. It comes with a simple cli tool that can be hooked up as a package.json script. Then you would do something like npm run gitbook && npm run gh-deploy to update the content. It will require book.json (metadata) and SUMMARY.md (TOC, points at content) but once those have been set up the process should work I think.

If you want I can set it up.

[bebraw]

Gitbook based build is running now. See http://christianalfoni.github.io/react-webpack-cookbook/ .

Notes:

• Gitbook summary (ie. toc) gets generated based on the sidebar. It is important not to break its structure (ie. add extra newlines between lists)
• Adding special characters to page titles breaks those pages (not accessible). This is due to encoding. The markdown links get encoded but the actual filenames don't. It is quite possible to solve this but I didn't spend too much time on this yet as it's just a proof of concept.
• You should add proper introduction per section. Now I just reused some existing pages. Push the current intros to subsections of their own.
• It is possible to add more functionality to the book (ie. meta + plugins). Example from Survive JS - https://github.com/bebraw/survive-js/blob/master/book.json .

[christianalfoni]

Hey! This is awesome! I really like this format, and as you say, it is possible to add more features.

I have been thinking a bit on the format of each page. I will by writing up some more today, try to keep things a bit simpler. Think of the content more as "reference page" than a "tutorial page". Very often you just want to get in and do one specific thing and the most important thing is the code examples I think.

Or maybe split things up in: Tutorials and HowTos. Anyways, we can just keep iterating and we will land on some good formats eventually.

This is really great work! I have been getting more feedback on webpack and React JS so there seems to be more interest in it these days. Good timing for a cookbook :-)

[bebraw]

Or maybe split things up in: Tutorials and HowTos. Anyways, we can just keep iterating and we will land on some good formats eventually.

Maybe this could be reflected in the sectioning somehow. Current ones (basic, advanced, theory) don't tell a lot. How about React? The cookbook should be about Webpack and React after all. Here's a sectioning that would make sense to me at the moment:

• Getting Started with Webpack - complements official getting started tutorial for Webpack
  • Running a workflow
  • Loading files
  • Writing loaders
• Webpack and React
  • Setting it up (hot loader, es6 etc.)
  • Flow
  • Authoring libraries
  • ???
• Going to Production
  • Structuring configuration
  • Hashing etc. - Rename (currently Dealing with production)
  • ???

You could either read this linearly or just pick the parts you find interesting. For instance if you are already familiar with Webpack, perhaps you would like to read just production bits. Or if you are new to React, start from there.

Once the structure starts to stabilize and we have content together, it would make sense to write concrete code examples for various parts in the repo.

[bebraw]

I suppose we can close this now.