A community effort to improve Discourse's documentation

documentation
multi-lingual

(Erlend Sogge Heggen) #1

Me too! I was hoping some of these fine folks might be interested as well:

@elberet, @blake , @elberet, @trident, @sander78, @Mittineague, @DeanMarkTaylor, @cpradio, @mcwumbly & whoever else has some time and expertise to spare.

The core devs are swamped, yet there’s a lot of groundwork that can be done by the community alone, so I figure we give that a shot.

The current state of affairs

Discourse’s documentation is in flux. Bits of information are spread across a wide assortment of sources:

  • How-to threads
  • ordinary threads (some in Dev and Features for instance)
  • external forum threads (e.g. sitepoint)
  • blogs (codinghorror.com, samsaffron.com, eviltrout.com…)
  • github repositories (discourse/discourse, discourse/wp-discourse, discourse/discourse-tagging…)

I’d like to make all of this content aggregated into a centralised collection of documents, structured in a way that makes it easily digestible.

Two domains would suffice:

api.discourse.org

  • A Slate wiki with @blake’s API doc ported over and continued.
  • Each section could have a “ask a question” link pre-filled with the Extensions category and some boilerplate text.

docs.discourse.org

  • A Jekyll site.
  • Corresponding Meta topic for each static page (i.e. a .markdown document).
  • would have two main sections:

docs.discourse.org/dev/

A collection of developer-centric tutorials, from how to install Discourse to how to write plugins.

docs.discourse.org/guide/

User- and admin-centric tutorials and in-depth explanations of unique features such a Likes and Trust Levels, and in-depth explanations of moderation tools.

TO-DOs

The bulk of this work can be done without any direct involvement from the core developers. The sites can start off on an unofficial domain and lots of docs already exist in topics.

  • Aggregate content that’s spread across the web ( @erlend_sh )
  • Set up Slate API site. ( @? )
  • Set up basic Jekyll doc site. ( @? )
  • Attach existing topics to corresponding docs ( @erlend_sh )
  • Write User Guides ( @erlend_sh, @? )
  • Write Developer Docs ( @? )
  • Create custom Onebox engine for Meta ( @? )

Bonus: Make a boilerplate plugin!

I previously aired the idea of having a Discourse equivalent of the WordPress Plugin Boilerplate and it struck a chord. It seems @Mittineague has already made some great headway with a simple discourse plugin and a not so simple discourse plugin.

Perhaps this work could serve as the basis for an official “Discourse Plugin Boilerplate” tutorial + example code? (e.g. hosted in /discourse/example_plugin)


Unofficial community docs - learndiscourse.org
Discourse documentation
Definitive and Explicit Guide to Plugin Development is Needed
Big Picture Features Poll
(Sander Datema) #2

Love the idea.

I’d like to have a role as an editor: writing text isn’t my greatest hobby, I’m better at instant responses to questions. But I’m quite good at looking at the bigger picture en helping to make a text/documentation flow right (I’m a teacher).

And afterwards I’ll try to get all this translated to Dutch as well. I suppose that’s also a plan, having the docs translated?


(Mittineague) #3

I’m still learning and haven’t studied all ~7K files ~200 gems yet :wink:
But I’d be happy to share what I know.

Maybe @TechnoBear would be interested and have some time to help a bit with UI and keyboard documentation?


(Dave McClure) #4

would be happy to help out @erlend_sh. maybe we can pick one place to start though and go from there? what do you think the best place to start would be? user guide / wiki?


(Erlend Sogge Heggen) #5

[quote=“Mittineague, post:3, topic:29129”]
I’d be happy to share what I know.
[/quote]Great. For starters, would it be okay to bring your tutorials from SitePoint over to new topics in the How-to category here? (and link to here from there instead). They’d get better exposure among Discourse developers here.

I’m gonna be getting started on User Guide docs in about a week from now. Have to finish the feature clips for v1.3 first.

Anything on the about page is up for grabs really. Lots of features there that could benefit from a full-page explanation. The ones on my personal to-do list are:

  • Likes (almost done)
  • Badges (will also touch on groups)
  • Trust Levels (pretty much done)
  • Community Moderation
  • Wiki Posts

For now, all new content can be added to the How-to category. Hopefully someone can step up to create the Slate and/or Jekyll site.


(Dave McClure) #6

I’ve been playing around with Jekyll / Github Pages recently… I may be able to help on that front. Can you point me to a few examples of doc sites that look like what you have in mind?


(Michael Downey) #7

Love seeing this effort. Just putting this out there if it’s still on the radar in September:

http://openhelpconference.com/

The 2015 Open Help Conference & Sprints takes place September 26-30 in downtown Cincinnati, Ohio. Open Help brings together leaders in open source documentation and support, as well as people from across the technical communications industry who are interested in community-based help.

The Open Help Conference features two days of presentations and open discussions. In true open source spirit, our discussions and agenda are led by our attendees, allowing you to learn and share what matters to you most. With some of the most interesting people in the industry, the Open Help Conference showcases the ideas that are shaping the future of help.

Following the conference, multiple teams take part in the Open Help Sprints, collaborative team meetings where people put ideas to work. Don’t have a team to bring to the sprint? Join us anyway and learn from the people who are pioneering documentation sprints.

If a handful of people were able to make it there, it could be a good opportunity for a focused documentation sprint. It’s a great little event, and the one where I first heard about Discourse from @jorge_castro a few years back. :slight_smile:


(Manthan Mallikarjun) #8

Hey! I can setup a Jekyll wiki. Are we going to host it for free on GitHub or are we going host them on private servers?

I have no experience with slate but I can try to set it up as well.

Edit: What’s a boilerplate?


(Erlend Sogge Heggen) #9

Sure. I think it’s best to start the site off as basic as possible. It may not even require search. Some examples:

A bare basics, standards compliant, up to date theme should suffice. Like Lanyon. Got any other suggestions?

[quote=“nahtnam, post:8, topic:29129”]
Are we going to host it for free on GitHub or are we going host them on private servers?
[/quote]We might want some plugins, so maybe GitHub isn’t ideal as the actual host, but we’d definitely want to sync with it to enable community-editing.

I know of at least two static website hosting services that have free plans, along with GitHub sync:

Will you please figure out between the two of you who’s gonna set it up? Or you could just experiment individually and we’ll take it from there.

Well, in the context of a plugin, it’s intended to be a bare-basics starting point that most plugins will have in common. Scaffolding, essentially.


(Erick Guan) #10

Now that we the community are going to make the doc site, we should made it international. Especially I already translated about 30 how to :smile:

What’s that?

We got different kinds of plugins(login strategy, powerful plugin poll, assets plugin) which needs different kinds of boilerplate.

Can you address a little more about why Slate is a good choice for a API doc site?


(Erlend Sogge Heggen) #11

Oh, great point. Whoever ends up taking care of the Jekyll install needs to figure out which multilanguage strategy we’ll go with (currently down). Here are two non-intrusive approaches:

[quote=“fantasticfears, post:10, topic:29129”]
Especially I already translated about 30 how to
[/quote]Wow! Yeah, we definitely need to showcase stuff like that more prominently.

[quote=“fantasticfears, post:10, topic:29129”]
[Onebox] What’s that?
[/quote]What is a onebox? It’s yet another thing that should have its own doc page :wink: As for what I want to do with it, that part is probably the biggest reach out of all these TO-DOs.

The idea is to make a custom onebox engine (CTRL+F for engine) that recognizes docs.discourse.org links and embeds them into Discourse topics. This will make their contents fully searchable on the forum.

[quote=“fantasticfears, post:10, topic:29129”]
We got different kinds of plugins(login strategy, powerful plugin poll, assets plugin) which needs different kinds of boilerplate.
[/quote]Good point. I’m just looking to gather some properly documented examples. I’ll leave it up to you developers to figure out what budding Discourse developers need the most to get started.

[quote=“fantasticfears, post:10, topic:29129”]
Can you address a little more about why Slate is a good choice for a API doc site?
[/quote]My main reason is the same as for Jekyll: It’s just Markdown files, so there’s minimal tool lock-in. Migrating to a different solution at a later point in time would be pretty easy. Here’s a rundown:

It’s also GitHub-friendly.


(Manthan Mallikarjun) #12

Github does support plugins.

https://help.github.com/articles/using-jekyll-plugins-with-github-pages/


(Christopher McEwan) #13

Great idea. Speaking as a noob, this would very valuable resource. If you want ‘Noob Testing Panel’ to see if instructions are sufficiently idiot proof, I’ll volunteer. :smile:

Might be worth considering an additional category for admins, as distinct from users or developers? There are issues that are invisible to users and probably trivial for developers but, speaking personally, challenging for non-tech admins eg. use of CSS, domain configurations,extracting poll results, interface with AWS S3, forum transfer processes,etc.


(Mittineague) #14

This is exactly what I need.

I like to think I write fairly well -but- I know that from being “too close” to the code and processes I can gloss over, omit, or at best not be as clear as I think I’m being.


(Sam Saffron) #15

My favorite API documentation is http://api.stackexchange.com/ I think this is where we should eventually aim to get.


(Erlend Sogge Heggen) #16

It supports some plugins, yes. But that’s because they’re part of the bundle. You can’t install any other plugins besides those, unless you apply one of the workarounds, which always involves some form of generating the site on a different server before you push the static site to GitHub Pages.

That being said, we may not need any plugins to begin with. I’d recommend doing the initial setup with plain GitHub pages.

[quote=“ChristopherMcEwan, post:13, topic:29129”]
Might be worth considering an additional category for admins, as distinct from users or developers?
[/quote]Ah yes, we’d definitely want that. I’ve added a note about it.

[quote=“sam, post:15, topic:29129”]
My favorite API documentation is http://api.stackexchange.com/ I think this is where we should eventually aim to get.
[/quote]The “Try it” feature is really cool! I’ve never seen that before.

This would certainly be very nice, but getting there would require more custom work and coordination than we can realistically hope for in a v1.


(Sebastian) #17

Maybe some tools/services like apiblueprint or swagger could do the trick here. It seems like they can be used for that kind of doc generation including automatic “try it” features quite similiar to what the stackexchange apis are using.


(Erick Guan) #18

API site use Swagger

And I port most of API to the swagger for a try instead of Slate. I read through some conversions. Many said Slate is more like a documentation instead of API spec stuff. Instead, I tried Slate. I feel quite good to write swagger though I didn’t try the Slate.

You can find the swagger spec for Discourse(most ported) down here:

You can open the swagger editor online and copy the yaml file to the editor to see what’s it looks like.
Swagger also comes with swagger-ui which is a static site generator with try features. It’s reasonable powerful and convenient.
I believe we don’t need a full site to host the API right now, do we? It’s a big project to write them down. When the doc actually stable, we may use swagger-ui or just write our own.

What’s your thoughts about Slate and Swagger. Is it hard to learn?

Doc site

I’d like to move on to the doc site now.

Would you like to design the v0 version? :stuck_out_tongue:


Swagger, WADL or similar for the REST API?
(Mittineague) #19

I’ve been thinking some sort of Discourse specific Glossary might be a good idea.eg.
hamburger - the three line icon in the upper right that opens a menu
onebox - the embedding of images and excerpts for some links when placed on their own line


(Dave McClure) #20

If @nahtnam doesn’t beat me to it, I can try some things out in the next few days.