Proposing Jekyll as community wiki platform


(Erlend Sogge Heggen) #1

Continuing the discussion from All the options to deploy Discourse with their relative pros and cons:

I suggest running an openly editable Jekyll wiki, probably on GitHub, with editing support via prose.io. You could enable plugins the simple way or the advanced way. Then you could use @trident’s awesome Jekyll integration plugin to create discussions-per-page.


Wiki topics
Community Editing
In your opinion, what is the best wiki engine to be associated with discourse?
Embedding Discourse content in remote pages, like a wiki
(Ben T) #2

The simple way actually works fairly well. But, it’s only hooked to the “best” comments, and since it’s not directly integrated with github it has to be manually generated and uploaded. So there would have to be a server out there that generates the site and pushes it to the repository.

A little more on the second point: You can’t add just any plugin to github pages, because arbitrary code could be run that way. I’m not sure if this plugin is the best candidate for inclusion with their basic set of plugins, because it opens lots of HTTP connections on the first generation.

It would still be very neat though, and it’d be cool to see where this goes.


(Sjors) #3

I don’t know, when Discourse would introduce a community wiki feature, I don’t want it to reside on a different platform. I think the implementation should be the same like how the stackexchange network does it, simple and it works.

It shouldn’t try to be a complete system like wikipedia, just the basics. Allow multiple users to work on a thread or post, by marking it community wiki. That’s it.

This would make Discourse more suitable for placing tutorials/articles right on the platform itself, so I don’t have to deploy other software for this purpose.

I would totally love to have this feature, in my view it would make Discourse stand out even more compared to other forums. Other forums don’t support this as far as I know.

Use case example: Tutorials - Windows 7 Help Forums

Sometimes readers recognize small mistakes in a specific tutorial, and they’ll post it under the tutorial. The tutorial gets updated and the useless reply is left behind.

With the introduction of a community wiki the user can propose the mistake, and it’ll get updated without leaving behind useless replies. It also encourages other users to contribute.

I think the Discourse founders understand this concept better then anyone else, because of stackexchange. But I wanted to elaborate on this anyway for clarification. :slight_smile:


(Michael - DiscourseHosting.com) #4

This sounds like you see the community wiki like a feature, part of the product, so everyone can have their own community wiki.

I thought that the community wiki would be more like meta, i.e. one central system to aid in “Discourse the company” reaching out to it’s user base.

Funny how two people can interpret something in completely different ways. Now who’s “wrong” ? :smile:


"It's too complicated" complain the users. How did you find the user migration experience?
(Sjors) #5

Not at all, take a look at this thread on SO: Learning Ruby on Rails - Stack Overflow

Notice all the posts are marked community wiki, this means everyone can edit/improve the answers.

I would love the same functionality on Discourse, so for example, everyone can help update the following thread. It’s also very helpful for tutorials/how to’s.

http://meta.discourse.org/t/all-the-options-to-deploy-discourse-with-their-relative-pros-and-cons/9631


(Erlend Sogge Heggen) #6

This also depends on whether the “community wiki” and the “Discourse docs/wiki” will the the one and same thing. If they’re separate, then a Discourse-powered community wiki could probably work quite well. If they’re the same, I think Jekyll would work better.

Jekyll pros

  • It’ll be joined with the developers’ workflow, effectively decreasing the friction between writing code and writing documentation.
  • Could mesh well with the eventual Discourse plugin repository, by making “docs are in the [GitHub] code repo” the standard.
  • Puts visibility of documentation changes on the same level as code changes. Documenters could track their past commits as effectively as developers.
  • Wiki editing and reading could happen anywhere; from the comfort of your IDE or a web frontend.
  • Distributed docs, i.e. more safe-guards, thanks to GitHub and forks.
  • Edits can be made without hesitation by creating pull requests for trusted mods to review. Takes the reluctance out of “edit fear”. This means you could encourage novice users to go ahead and suggest wiki improvements without loss of quality and more engagement.
  • Greater formatting & theme styling freedom
  • Multilingual support via plugin, and I do believe it would work with tools like Transifex as well.
  • Super light on resources
  • Can easily be exported as a book using gitbook.io

Jekyll cons

  • Relies on plugin for integration. Won’t ever be as tightly integrated as plain Discourse with native wiki add-ons.

  • Deals with GitHub users instead of Discourse users. Could make it more difficult for future achievement tie-ins and such.

  • The whole GitHub+Jekyll+Plugins+Prose.io+Self-hosted mix is a tad complicated.


(Erlend Sogge Heggen) #7

To be honest, I would love to see both. Jekyll for the official wiki and Discourse for the community wiki. Under ordinary circumstances that’d be unnecessarily complicated (pick ONE!), but I think both approaches are important first-hand experiences for the Discourse developers to have.

  • On the one hand they’ll be integrating Discourse with an existing platform.
  • On the other hand they’ll be extending Discourse to imitate an established workflow.

Both are very important aspects of Discourse that ought to be pushed to their limit.


(Michael - DiscourseHosting.com) #8

That’s a use case with a pretty limited audience though. “That’s plugin material”, IMHO. I think Discourse benefits more by focusing on the core features for a forum.

I like your Jekyll proposal - a lot.


(Erlend Sogge Heggen) #9

Not limited if you think of it in terms of pushing the boundaries of Discourse’s extensibility.

But I like my Jekyll proposal a lot too :cake:


(Erlend Sogge Heggen) #10

Here are some cool examples of projects using Jekyll for documentation:


http://about.travis-ci.org/docs/


http://sendgrid.com/docs/

http://docs.scala-lang.org/contribute.html
http://docs.scala-lang.org/

http://untyped.com/untyping/2013/08/07/writing-documentation-using-grunt-and-jekyll/
http://help.mynaweb.com/

(I think the main thing all of these sites are missing is a simple “Edit” button that would take you to the respective file on GitHub - Edit: SendGrid has it, nice!)


(Dave McClure) #11

This post is an implicit vote for something like the Jekyll plugin :slight_smile:

https://meta.discourse.org/t/beginners-guide-to-deploy-discourse-on-digital-ocean-using-docker/12156/70?source_topic_id=9873

(Jeff Atwood) #12

Ultimately install stuff needs to live with all the other install docs, though:


(Erlend Sogge Heggen) #13

No doubt, but that kind of doc should be kept in sync with a more universally accessible and SEO-friendly web page anyhow. It won’t require anything more than a “Please only edit this doc from this location”, similar to how translators who view the YAML files now get redirected to Transifex.

p.s. I found a beautiful new Jekyll-based wiki example, the Ionic Framework docs.


(Erlend Sogge Heggen) #14

p.p.s Isn’t this one of the few things Git Submodules is actually well suited for?

You could have a dedicated docs repo&site like https://github.com/discourse/docs and keep a sub-module for it in /discourse/discourse.


On a different note, has anyone tried gitbook.io? It looks really interesting!

Publish books using Git and Markdown

Even comes with a native cross-platform editor!


(Kane York) #15

Mmm, but submodules still require a diff in the main repo to update. Additionally, it’s an additional cloning and updating step:

git clone -r <discourse>

or

git clone <discourse>
cd discourse
git submodule init
git submodule update

(YCH) #16

If Discourse should have a ‘community driven document’ feature someday, I would like to see these things.

  • Someone post.
  • People provide feedback.
  • OP corrects and improves post continuously. It become somewhat well written document.
  • Admin grants post as like ‘Community Proved’, ‘Hall Of Fame’, ‘Best Tutorial’ or whatever honorable.
  • Post get specialized style view as like independent document.
  • If OP edit it, send diff view update mail to subscriber addition to regular reply. Or generate ‘diff view’ reply automatically.
  • If necessary, other granted users can edit post.
  • People still can reply as usual topic thread.
  • There are TOC page or category for granted posts.

It might look like ‘FAQ + tutorial + Best Articles’ list for community.

I like wiki’s concept. wiki.archlinux.org and wikipedia are my favourits.

Wiki’s approach is ‘Document first, then conversation’. But I believe ‘Conversation first then document’ approach is better for more participants.

I saw so many people who are afraid of ‘edit document looks like official and formal’. They are just afraid of it and hesitate it. But OK about commenting their opinion independently.

We have nice conversation platform already. Also we have nice document editor. I think we just need somewhat special place and style for ‘Document like posts’.


(Erlend Sogge Heggen) #17

Nearly two years later, I still think this is the way to go. The basic setup would be as follows:

  • Anything that is worthy of documentation would have a static page dedicated to it, e.g.:
    doc.discourse.org/how-to-create-foobar
  • A corresponding thread would be created on Meta in the appropriate category, and attached to the static page. It would merely appear at the bottom as a “Comment on this page” button – no need to embed posts.
  • The thread would hold a URL pointing to the doc page.
  • The URL would be oneboxed with the complete contents of the page included, thanks to a custom onebox engine.
  • This also makes the contents of the thread searchable.

None of this would have to be automated in v1, if ever. Copying some links around is easy enough.

Edit Flow

  1. Click “Edit this page”
  2. Redirected to GitHub
  3. Edit page contents on GitHub
  4. Submit pull request
  5. Accept pull request

Could be simplified by having a trusted group of Docs contributors on Github who could commit directly. In my experience, 95% of docs tend to be maintained by a core group anyhow.

Another big bonus would be an on-page editor.

New Page Flow

  1. Create and edit new file on GitHub
  2. Create pull request.
  3. Accept pull request.

It’s tempting to go the embedded route - the major benefit being that it sticks strictly to Discourse concepts - but it falls short on some critical areas:

  • Doesn’t track and credit multiple authors as well as Git/GitHub

  • Topic creators (receiver of likes) are disproportionately rewarded from editors.

  • Handling multilingual articles will require some trickery (although not unfeasible)

  • There’s more “magic” to it. Plain .markdown files are more future proof malleable.


A community effort to improve Discourse's documentation
(Tobias Eigen) #18

I’m super excited you’re getting into community documentation for discourse! And I think this jekyll approach can work well. But how far are we from being able to do this the discourse way, using discourse wiki topics? What is missing that can’t be/shouldn’t be added anyway to make Discourse truly great?

It seems a shame to not be “dogfooding” for documentation as we have been doing so far. Not all of us spend that much time on github. And oneboxing documentation in meta topics that are maintained elsewhere seems like a bandaid.

The only features I am really missing from wiki topics:

I also think it would be interesting to create an external app that can take a file containing raw topic URLs and use it to generate a structured document in one place. It would be configurable with headers and footers, with or without links to the source topics, and with our without references to authors/follow-up posts/etc.


(David García-Navas) #19

Great topic!

Just wondering… if Discourse already have topics that are processed like pages (e.g. FAQ/Guidelines is a topic that staff could edit and it is showed like a page)… Could this feature be extended to serve as wiki purposes?


(Erlend Sogge Heggen) #20

These are not small things though, and are not likely to make it into Discourse any time soon. The v1 documentation initiative is all about having something ready for prospective Discourse users to consume within couple of weeks, or months at the most. I don’t want to get caught up in a web of dependencies, and I don’t want to take time away from the core developers’ already full schedules.

“The Discourse way” isn’t necessarily to do every conceivable type of content creation in Discourse. It is for that exact reason that the core team is using WordPress instead of Discourse as their blogging tool. Having “Discuss this page” links on every wiki page is very much in line with “The Discourse Way” if you ask me.

You should aim to have the bulk of your content funneled through Discourse, but you shouldn’t be using Discourse to serve all your content-creation needs.