Any plans for admin/user docs with 1.0 release?


(Michael Downey) #1

So there’s currently some great documentation for Discourse:

  • Relatively thorough installation guides on GitHub
  • Some rudimentary troubleshooting tips on GitHub
  • Developer guides on GitHub
  • HOWTO category here on meta
  • A massive slew of knowledge in the various categories on meta, that is maybe-searchable but that would have to be gleaned out.

The last item is what I’m thinking about. Is there any plan to synthesize some of the concepts and basics of Discourse into a general admin guide that ships with the software as part of the V1 release? For example, such documentation might include:

  • Explanations of roles (moderator vs. admin), levels, and badges
  • How things like categories, sub-categories, and uncategorized are designed to be used
  • How pins work
  • The ideas behind flagging and what happens when different options are chosen
  • General guidance on UI customization
  • Differences between new & unread, and the various colors & types of count badges
  • Differences between and explanations of starred, watched, tracked, muted, etc.
  • Other stuff that I surely can’t think off at the moment

Discourse is great software and I’d hate for people to be held back from implementing it because they can’t quickly/easily understand how it’s designed to work. Do others agree/disagree?


(Jeff Atwood) #2

Well, there is a basic getting started admin guide which ships with every copy of Discourse. It is a staff topic with the title

READ ME FIRST: Admin Quick Start Guide

I’ll update that again now with some ideas you gave me based on the above.

There’s also the new user PM that goes out to every user after they sign up, with basic tips on how to use Discourse. We’ll be improving that a bit (adding some animated GIFs of demos) before V1.0.

We’ve only just now been able to get everything in place to the point that it wasn’t constantly changing – you can’t write “docs” on shifting sand.

Per your last set of bullets, it might be a good idea to start on some additional, focused HOWTO guides if people feel they are needed. But please, keep them small and focused, I want to avoid the TL;DR kitchen sink docs type format if we can.


(Michael Downey) #3

The admin guide is looking pretty nice! It’s a shame that older installations can’t somehow be updated, as mine is older and missing some of that new content. :smile:

Will the new user PM content get updated by updating from master when the time comes?

Will think a bit and ask some other folks about potential HOWTO’s.


(Dave McClure) #4

Make a link to it somewhere in your staff category so you can always get the up-to-date version!

And if they deserve to be part of the larger admin or user guide narrative, then perhaps add them as links within those docs (as you’ll notice the Admin guide currently does link to a number of HOWTO’s).


(Sam Saffron) #5

Closing this, we ship all new installs with a bunch of moderator only topics to cover this.


(Sam Saffron) #6