Creating an FAQ for the bbPress Codex
I’ve been trying to help out with the bbPress Codex when I get some free time. Something I’d like to create is an FAQ covering issues that come up again and again. Or even two FAQs:
FAQ – Getting Started with bbPress
FAQ – Troubleshooting
The best resource for an FAQ is often a support forum so if there are any questions you’d like to see in an FAQ please add them here. Or just drop in a link to a support forum post where a question has been raised. I’ll turn it into a question in the FAQ.
Also – if there are any other docs that are desperately needed let me know and I’ll put them together. I don’t have loads of time but I reckon if I make a list I could write doc a week.
Thanks for helping out 🙂
Cheers, I think there is the start of the FAQ page in ‘drafts’ on the codex.
Hi Siobhan, Jared… we’ve seemed to get a bunch of folks who have been helped with basic setup from using our Forum Flavors video, located here: http://labsecrets.com/2012/01/23/buddypress-and-bbpress-forums-made-easy/
Would love to help out in your documentation/tutorial project, including releasing some “ready to use” bbPress child themes that work out of the box with some of the most popular WP parents in the repository.
Please let me know if you are open to that?
John James JacobyKeymaster
Thanks everyone again for taking this and running with it. It’s a huge, huge help.
Awesome! It’d be great to have a push on getting a complete bbPress Codex.
Some general thoughts:
Planning the architecture is really important. I get brought on board with a lot of doc projects at a late stage. When no planning has gone into it the docs end up getting unwieldy and difficult to navigate. People just randomly add docs until there is a mountain of information and no user-friendly way of navigating through it. If there is a sound structure from the start it makes sure the complete documentation holds together as it grows.
We should create some sort of task list of doc we would like to see and things to work on. We could use a P2 or a wordpress.com blog, or we could try using bbPress itself for management. If we had a bbPress docs forum then we could add doc suggestions as topics. When a person decides to do it, it becomes a sticky (so that no one else works on it). We could tag posts as idea, in progress, and complete – people would be able to discuss individual posts in the threads. It might be fun to try using bbPress in this way.
Okay – those are just some ideas. Feel free to disregard – just thought it would be good to get a discussion going.
Yeah a couple different FAQs would be really awesome.
- What do I need to get started?
- How do I set up user role permissions for adding new forums/topics, etc.
- How do bbPress and BuddyPress work together? (when to use what?)
- Where can I go for bbPress plugins?
If @labsecrets has some time to help with the theme compat stuff that would be awesome! I’ve had that on my list since one of the 2.1 betas was released but haven’t gone beyond a basic outline yet. Happy to share what I have on that as well.
we would be able to launch right out of the gate with our Responsive Child Theme (based on Emil’s awesome “Responsive” Parent), specifically for bbPress. This is one of our most popular child themes right now, and I think he has more than 170,000 downloads..so maybe a good way to get bbPress “mainstream” and responsive in one swoop.
We would be also able to provide step by step videos and user-manual for the child theme(s) and support customization questions.
You can see it in action here (this is the premium version with BuddyPress and WooCommerce integration as well…the bbPress only would be free, of course)
We also have a version that has special features for folks who want to start a video membership site. See: http://labsecrets.com/demo/responsive-labvidz-bbpress/
The child theme is ready to use now, so as soon as an organizational method is figured out, we can put it up.
All in all, we can give folks a pretty “direct to the result” way to get started…
@Siobhan I like the idea of using bbPress for a docs task list
@labsecrets Thats some pretty impressive stuff you got there
Mason and I started to come up with a task list after talking to John at WCNYC. Here’s what we came up with:
Setting up and running your forum
bbPress settings (I have some content for this somewhere – will add it as a draft)
Customizing how bbPress works
Useful plugins that extend bbPress
Moderating and managing your forum
We also had:
WordPress User Roles and bbPress
Getting Started with bbPress
They are complete though.
Since you guys are on the ground supporting bbPress users, what things in the docs would you like to see prioritized?
Sounds good… would love to put the emphasis on the end-use of the forums in some way too. A lot of our users come to us with their intended solution (goal of using bbPress) already in mind. Might be helpful to focus one section on that as well, so folks could work backwards.
How do you want to put up the skeleton of these docs?
It would be quite nice to have some of the most commonly asked forum questions somewhere and then a couple of useful topics users can check out.
I know that customizing bbp_list_forums is a popular one.
It’s a good idea to split docs out into Developer Docs and User Docs – the user docs could then be split into installation, troubleshooting, and using.
@lynq – can you drop links to some of the commonly asked questions in here?
The codex is currently setup with a ‘context’ category that lets us split the docs between developer and user.
https://codex.bbpress.org/context/developer/ & https://codex.bbpress.org/context/user/
Building on that already existing theory as we reply to questions in the forum we should start tagging them appropriately ‘user’ or ‘developer’ and thus being able to follow each tag.
https://bbpress.org/forums/topic-tag/user/ & https://bbpress.org/forums/topic-tag/developer/
Should we also add other tags like ‘faq’ or ‘addtofaq’ or something along those lines so we can add tags to be able to follow topics we think need docs/updated docs/better docs and priority of that need etc etc… Suggestions?
Is ‘User” to dis-ambiguous in the ‘docs’ vs ‘end user username’ context for bbPress though?
(If we were able to edit the current topic tags we could quickly tag the past couple of weeks topics, als that will have to wait a little while longer)
- This reply was modified 10 years, 10 months ago by Stephen Edgar.
Sorry for the delay to this – i’m semi-on holiday 🙂
So this is an interesting question to do with users, end users etc. In fact, should we be producing stuff for forum users as well? I guess we have three groups: Developers Forum Admins Forum Users
Would that make more sense?
How about we adopt the following tagging system:
faq – for something to be added to the faq document – for something to be documented
Would that make sense? Is there any way to subscribe to tag feeds?
- This reply was modified 10 years, 10 months ago by Siobhan.
In the past we’ve found it helpful to have one set of docs and info relating to “use” of the system, and then a second relating to “development” (or “customization”). The differentiation is less on the capability of the person searching, and more about what the point of the information may be.
Think of it like an automobile. There is the “user manual” in the glove box. But if you are a mechanic, you probably have the Chilton “repair manual” for that car in your shop somewhere.
If you use bbPress, the default “user manual” would have a variety of useful “how to use and extend this” info… but if you wanted to get into the code (php or css or js or shortcodes) you would look to the “repair manual” (not implying anything broken, just meaning it’s for modifying code)
Keeping things as simple and flat as possible might help to eliminate hiding good info in a complex heirarchy?
Yup, I get that. But there is still a distinction between 1) the people who install and use bbPress to run their forum, and b) the forum members. What I’m wondering is whether we need to provide anything for the forum members (like basic stuff on posting etc) or if we can forget about them. In which case there are just Devs & users.
I was thinking we could provide a “users guide” with videos (think like Shawn has done with WP101) for bbPress “users” and in the same area the “admin guide” with info about running the site. Perhaps we can set aside the user content in a way that can be shared universally by site admins. We have the means and mechanism to deliver the content that way via a plugin, embed codes, etc. so a site owner could have generic “this is how to use it” instructions…. again, very much like wp101. We would donate our time and effort to produce this for bbPress if you guys are open to receiving the same?
Sounds like a good idea to me – lots of users find videos really useful. I guess see what everyone else thinks?
I have created an FAQ here: https://codex.bbpress.org/faq/
It’s not published yet but you can see it if you’re logged it. I realised that one had already been started once I’d done it but it only had one question so I integrated it. At the minute I’m just coding the links using an a name – is this the best way or is there a plugin we should be using?
Also, once something has been added to the FAQ is there any way to “untag” it? Should I comment on the thread that it has been added to and someone else can remove the tag?
Can someone from the group (or John?) please advise how you prefer for us to handle referencing our video content? We current, for example, have this popular video: http://labsecrets.com/2012/01/23/buddypress-and-bbpress-forums-made-easy/
Should we grab the embed code and put it into the codex as needed for each video, or do you prefer we keep embeds outside the codex and link to it directly.
Based on previous discussions with John, I do not want to create an improper embeds or links to our commercial endeavors…
See, eg., our addition to https://codex.bbpress.org/getting-started-with-bbpress/ (re. BuddyPress and bbPress), this is where a video would be helpful.
We discussed using videos in the WordPress Codex. The consensus was that videos were great so long as they were done on an clean, unbranded WP install (localhost or something like that).
Thanks, I wasn’t here at that time, but good info.
The videos would not need to be embeded on any other site, they could “live” in an unbranded Wistia project container with the other bbPress-only videos.
Question Two: What about any standard leader-trailer info? If we want to do this “right” it seems we should take the extra time to have an agreed-upon leader and trailer for all these videos, as this would make them all feel professional and part of the bbPress “product”.
Any input previously shared on this point? If you want, I can create some samples and share them here.
Every thing up ^^^^ here looks and sounds good as does the FAQ 🙂
“Is there any way to subscribe to tag feeds?”
Only by RSS, just add /feed to the end or a tags URL https://bbpress.org/forums/topic-tag/faq/feed
“What I’m wondering is whether we need to provide anything for the forum members?”
As the docs get better I think they will be universal enough to be used by all parties and by utilizing a plugin such as https://wordpress.org/extend/plugins/bbpress-admin-bar-addition/ I think ‘the docs’ can be delivered to quite a few target audiences being discussed above.
> The new admin bar entries will only be displayed if the current user has the bbPress/ WordPress capability of moderate. (Note: I am open for suggestions here if this should maybe changed to a more suitable capability.)
Also see this TRAC ticket #1924 https://bbpress.trac.wordpress.org/ticket/1924
- This reply was modified 10 years, 10 months ago by Stephen Edgar.
I just published that FAQ and linked to it from the main page:
If you have any additions, revisions, edits or whatever go fo it.
I removed the BuddyPress section from the FAQ as after pointing someone to the FAQ I got a question “Do I have to install BuddyPress?” so to avoid confusion it is now separate.
- You must be logged in to reply to this topic.