Unofficial community docs - learndiscourse.org


(Erlend Sogge Heggen) #1

Continuing the discussion from A community effort to improve Discourse's documentation:

After a few occasional weekend sprints, I’m happy to share with you all what we’ve got so far:

Go have a look at learndiscourse.org, v1.0

Huge thanks goes out to @fantasticfears, @mcwumbly and @nahtnam for getting this off the ground together with me. We all owe a special thanks to @fantasticfears for doing most of the technical heavy lifting, which repeatedly gave the rest of us a much needed boost.

What is learndiscourse.org?

LearnDiscourse is just a Jekyll site, pulling all of its content from meta.discourse.org. It’s all of Meta’s How-to & FAQ articles, neatly categorised and collected into one clean overview.

The way it works is a mixture of automatic and manual labor. But the average doc contributor won’t ever have to leave Meta, or even learn any new conventions (though we might wanna try introduce some of those eventually).

To learn more about how it works, check out our WIP workflow doc.

We plan to keep iterating on this process, most likely introducing more advanced automation and build processes in the future.

What is the purpose of learndiscourse.org?

This site is our attempt at creating a proper documentation portal for the Discourse project. And since

  1. there’s already loads of top notch content hosted on Meta, and;
  2. Discourse has a top-of-the-line content editor…

…we concluded that the only major thing missing was a clear A-Z presentation layer. So that’s what the first iteration of learndiscourse.org is, and nothing more.

Going forward, I’m hoping Meta and LearnDiscourse can positively influence one another, and continue to be pulled ever closer together.

What does the “v1.0” mean?

This is merely the first iteration of the site. With more time and support, we’d like to keep on experimenting, as we have several ideas on how to make this site more useful. But before we get into that, this is what we’ll continue working on, content-wise, for v1.0:

Users

The current lineup isn’t very impressive, but I will continue creating original articles for the Users category, with hopefully other contributors joining in over time.

UPDATE: Made some good progress!

Moderators

Still very WIP. Hoping @mcwumbly can initiate some articles here once he’s got more time on his hands.

Administrators

In good shape! :content:

Designers

Also very sparse, and will probably stay that way until Discourse has more powerful theming capabilities built in.

Sysadmin

  • The Sub-categorisation (Install, Docker etc.) is pretty haphazardly done. Open to suggestions.
  • :white_check_mark: Install is missing proper install guide, see separate discussion.
  • :white_check_mark: Many docs might no longer be relevant and should be unlisted.

Developers

  • :white_check_mark: Environment: We’d like to move some external blog posts and github guides into one place.
  • Plugins: @Mittineague any plans to migrate your external tutorials to Meta?
  • Discourse as your first Rails App should be on Meta.
  • :white_check_mark: Would be nice to have @eviltrout’s embed article on Meta.
  • :white_check_mark: Many docs in Hacking might no longer be relevant and should be unlisted.

Known Issues

  • Order of sub-categories in sidebar doesn’t match order of corresponding subfolder.
  • Sidebar should show all articles of current sub-category?
  • No search yet.

Will gladly hear out UX suggestions or pull requests from designers! Special :rainbow: nudge to @awesomerobot and @rewphus.


Proposing Jekyll as community wiki platform
Maintaining install docs et al on Meta
Discourse documentation
A community effort to improve Discourse's documentation
Wiki sync plugin
Contributor Interviews – David Taylor
(Mittineague) #2

I got a bit lost with the “Jekyll” discussion and then RL stepped in and hasn’t let up much since. So I have gotten behind on other planned endeavors.
IMHO Robin’s tutorials * have already surpassed my level, but I can at some point if others think they might be helpful or provide a slightly different “spin” on plugin development.

* eg.


(Erlend Sogge Heggen) #3

No worries about losing track, that one’s on us. We picked up some momentum and decided not to bring more people into the mix at first to avoid the many-chefs problem.

I still think the more plugin examples we have the better. If parts of your tutorials have fallen behind, the best way to keep them up to date would be to give them more exposure here on Meta & learndiscourse.org.


(Jeff Atwood) #4

Looking great! Thanks for everyone’s hard work on this!


(Sam Saffron) #5

I love that the “source” of the various articles is on meta, I can totally see something like this becoming official, after all its just a repackaging of “meta” in highly structured site.

  • Can we make all the links to “source” hyperlink back to meta?

  • We should look at doing an “embed” for the replies and a continue discussion, on meta where appropriate (aka not closed)

Perhaps longer term, if this is successful, we can link back to learndiscourse from the topics that are included.


#6

Wow, very exciting! I could see myself using this all the time. I really like how it’s broken out in to functional categories based on common Discourse user roles. Would be nice in the future to maybe try to match those roles with categories here on meta, but I know there may not always be a direct correlation so it could be hard.

Only UX input so far is that the homepage could be more responsive, but with it’s current structure that can easily be addressed. That top navbar also isn’t really being utilized, but I’m not sure if you are keeping that open for future functionality (e.g. search), so not a big deal right now.

I would be more than happy to help in any way I can. Once I get a little more time to dive in to the repo I will let you know if I have any particular suggestions, but tremendous start everyone!


(Erlend Sogge Heggen) #7

Agreed. Added to issue#18.

[quote=“sam, post:5, topic:31931”]
We should look at doing an “embed” for the replies and a continue discussion, on meta where appropriate (aka not closed)
[/quote]You mean using the existing topics for comments right? Yeah I really wanna do that too. You can track it in issue#23.

[quote=“sam, post:5, topic:31931”]
Perhaps longer term, if this is successful, we can link back to learndiscourse from the topics that are included.
[/quote] :thumbsup:

[quote=“rewphus, post:6, topic:31931”]
I really like how it’s broken out in to functional categories based on common Discourse user roles. Would be nice in the future to maybe try to match those roles with categories here on meta, but I know there may not always be a direct correlation so it could be hard.
[/quote]Yes! Actually, we were planning to segue our way into that soon after this announcement. I’d really love it if we could:

  • Merge How-tos and FAQ into one “Docs” category.

  • Create sub-categories identical to Learndiscourse’s top-level categories (or sections, as we’ve been referring to them)

  • Optionally even add tags that mirror Learndiscourse’s sub-categories.


(Dave McClure) #8

In order to move things forward, I think the best approach right now is to find a way to start focusing on creating and curating content that doesn’t require us to update the category structure on meta first:

  1. create one topic to prioritize which content needs to be written or curated (ie, to discuss which articles/topics need to be added or updated). the original post can list out the ‘table of contents’ as a wiki and link to topics as they are identified or created. discussion below can focus around which things should be added/removed or reorganized in the toc

  2. anyone can then consult that table of contents list to create a topic for a documentation article and link to it from the main toc topic wiki post. then focus on the actual article / topic content

  3. put the document in the best appropriate category (faq if its not a how-to. uncategorized if it really doesn’t fit either) as more content gets added we can see whether it makes more sense to add/reorganize categories here.


(Erlend Sogge Heggen) #9

So, how can we start moving towards this?

@fantasticfears recently added support for GitHub imports, so now we’re aggregating the docs from the GitHub - discourse/discourse: A platform for community discussion. Free, open, simple. repository as well, e.g. for Install instructions. There’s something more proper about serving your Install page on your own domain, if I may be so bold :tophat:

I’d also like to enhance the feature matrix that is the about page by linking to extended articles about the different features listed. Eventually I’d love to help turn this page into something more akin to the likes of wordpress.com/features.

Some big ticket items remaining:

  • Rewriting external links: #29
  • Use source topics for comments: #23

Anything else that comes to mind?


(Erick Guan) #10

Import script is a temporary thing to do. It’s operated manually.
@erlend_sh added a plugin page recently. It’s also done manually.
We are quite repeating ourselves to do that. Maybe it’s a good reason to go to a rails project with CMS features.

Just a thought.


(Erlend Sogge Heggen) #11

It’s definitely something worth considering further down the line. The big benefits with our current approach is:

  • our infrastructure (GitHub) is completely free;
  • it’s very low maintenance (no Docker container to manage or a Rails app to keep up to date);
  • involving new contributors is as simple as adding them to our GitHub team, as opposed to messing with SSH keys and funny business like that;
  • the bus factor is very low. It won’t take a new contributor very long to wrap their head around what we’ve put together;
  • and finally it works, and there’s plenty of low hanging fruit to pluck off. There’s still a lot to learn from this first iteration.

Instead we pay the price of some manual labour, but really it’s quite trivial work. I’ll be sure to cry out if I get tired of it :smiley:


(Erlend Sogge Heggen) #12

I made some mockups to discuss some minor theme changes, primarily to do with the sidebar.

Front page

  1. Show sidebar on frontpage. I really feel this ties the site more together, and it puts a basic “sitemap” in the visitor’s head.
  2. Move category icons next to its respective heading to conserve space. (the header background colors should stay. I just didn’t include them in the mockup)
  3. Don’t extend the grey linebreaks to the very edge. Makes them less table-looking.
  4. I think we can remove the “More” link in favour of hotlinking the header. If we have the sidebar always present, there’s also the optional link there as a backup.
  5. Reduce the height of the colored header by about 20-30%. It’s a bit too powerful.

(Oh yeah, and I cheekily added a search bar, but nvm that)

Category page

  1. Supplement sidebar headers with icons? I’m still not sure, but I do like the look of the Stripe docs. The reason I don’t introduce them until you’ve drilled down one level is because it felt overloaded on the front page where there are already icons in use for the body’s box headers.
    (Note: Icons were just what I found in Moqups. Not trying to suggest new icons.)
  2. Bolden the active category section.
  3. Hide sub-headings in other categories? I kind of like it this way, with only the most important content visible.

Article page

  1. Remove indentation on first sub-heading to make room for 2nd level sub-heading.
  2. Instead of showing complete index of sub-category, just display the previous and next article in line to give the reader a sense of orientation.
  3. Moved “Source:” links to the bottom of the page. In the future they would ideally be replaced by a Comments link in this position anyhow.

(wups, Administrators icon disappeared. That’s unintentional)


Wanna mess with the Moqup? Shoot me a PM and I’ll give you edit privs.


(Erlend Sogge Heggen) #13

Both of the aforementioned issues are now done:

https://github.com/nahtnam/learndiscourse/issues/29

https://github.com/nahtnam/learndiscourse/pull/30

Though comments obviously won’t work until the remaining piece of the puzzle is configured on Meta’s end.


(harvey) #14

learndiscourse.org seems to have a few broken links. Is this still the go-to place to learn discourse?


(Erlend Sogge Heggen) #15

No, sorry about the confusion. Our #howto and #faq categories are the official learning hubs for Discourse. learndiscourse.org was merely an experiment, and it is not actively maintained.


(Erlend Sogge Heggen) #16