Expanding the codex
Someone asked me yesterday about what different group roles (Admin, Mod, Member) meant, mentioning that the BP codex didn’t contain any information about this issue. So I decided to be a good citizen and create a starting guide for group setup: http://codex.buddypress.org/getting-started/group-settings-and-roles/
I’d like to encourage others to take the initiative of expanding the codex when the opportunity arises. That is, if you see a question being answered time and time again on the buddypress.org forums, or if you find yourself constantly referring others to a particular tutorial on how to accomplish something in particular within BuddyPress, consider taking a few minutes and adding it to http://codex.buddypress.org.
Moreover, if you notice that existing pages are incomplete or out of date, feel free to click the Edit This Page button at the lower left and make the fix. If not you, then who?
Verily you are a good citizen
Codex is in desperate need of attention as you state. It would perhaps be a good idea if those that have a notion and the energy to add to it perhaps focussed initially on guides that were aimed more at the new user, novice user or Neophytes as a colleague was found of describing newcomers, for it is these users that are sometimes overwhelmed by pages such as http://codex.buddypress.org/how-to-guides/modifying-the-buddypress-admin-bar/ and need things simplified; it’s easy when one has long forgotten ones own development path just how confusing what may seem clear to us is in reality far from, in fact much is still confusing to me
Write but then then read as though you were just setting out on the arcane and lonely path of the coder.
+1 @hnla. The specific quote I got from the person who emailed me was: “BuddyPress appears to have a pretty skimpy codex, one that covers installation and technical issues more than descriptions of various parts of BP, like the how user roles are defined”.
The good news is that this is a part of the codex that a larger number of us would be able to contribute to – you don’t have to be a hardcore developer to write some good beginner’s documentation.
I agree the codex needs help. I’ll see about making a few additions. The more the better. If we all share just a little bit, it could be a great resource.
One thing we should take heart from: WP took years before there was anything resembling the codex they have now, in the beginning, and for what seemed like an age, it was pretty thin
Documentation! the coders favourite pastime
Hopefully we will all chip in and help, but we must have a few brave souls check it over from time to time and just ensure that entries are clear accurate and got the good grammer and spealings, oh and the punctuation thingies. (my personal bugbear)
I’d say add it regardless of if they are clear, accurate and have good grammar. People are usually happy to correct that part of it;-) It’s the starting it that people aren’t as good at.
I added a new section about accessing Group Info by the Group ID: http://codex.buddypress.org/developer-docs/action-reference/groups/
I thought it would fit better in a different place off the main page. Plus, I thought it might encourage other people to contribute similar tricks to accessing the BP data. However, it doesn’t seem like I can edit: http://codex.buddypress.org/home/ to be able to add a new link on that page to a new page. Do we need to create a bunch of “Stub” documentation pages so that people can start editing the stubs? Sure, it’s unfortunate when someone comes to the documentation and finds a stub, but it also could prompt people to make something of the stub.
I think that the only way to add new pages is to go to http://codex.buddypress.org/wp-admin > Pages. Make sure you give them the proper parents. (BTW – I’m unsure whether this option is available to everyone – let me know if it’s not and I’ll make stubs for you)
Guys Stubs are good in fact they can be important structural elements.
Boone I think it would be a good idea if the codex was set out with a few more category stubs to guide people to some extent in what sections are required or simply provide a hierarchical doc outline.
Can you edit this FAQ:
Can I run BuddyPress on a Windows server?
A: Don’t call Windows a server it’s a …
Actually a link to XAMPP might be helpful for those few not sure how to set up localhost dev environment
A Windows server is not just a WAMP package like XAMPP. It can be IIS as well, which is problematic as there are a lot of reported bugs between IIS and BP (mostly permalinks and 404 pages).
I can understand the purposes of the FAQ codex page; keep it simple, don’t inundate the reader with too much info.
I think I might need to create a sub-page for specific FAQs.
Don’t talk to me about IIS it’s a dog! have had the misfortune of having to maintain a production server running it, utter rubbish, gloamed onto all the IP addresses wouldn’t release any without a patch only available on disk! and as for mod_rewrite *deep sigh*
I think I might need to create a sub-page for specific FAQs.
wouldn’t get bogged down in too much detail, save that for a rainy day.
Stub suggestion: Troubleshooting 101
The absolute basic frequently encountered issues i.e the white screen – script memory limit; the whitescreen – disable all plugins, rename etc
I am most interested in the template tags page, which I find to be useful all the time but I suspect it is incomplete. Does anyone know of a way to automatically generate a list of all the tags currently used in the latest version of BP? Or does it just take hunting through the core?
I can do you action and filter names, but not template tags. However, look in the [component]/[component]-templatetags.php files – they’re all the template tags for each component.
Yes! Thanks I’m working on a little art/reference project.
Yep I can give it a go Ray it wasn’t intended as an instruction to anyone
I’ll be looking at the codex and seeing where I think I can contribute. documenting is however slow and methodical work, I’ll do what I can when I can and hopefully with all of us chipping in the codex can be expanded on a ongoing basis. even if it is a slow gradual process.
You know what would be really helpful? Even if you don’t want to do the slow, methodical stuff documentation itself, it would be very helpful to have a sketch or two of what the overall structure of the codex should be like.
- What are some pages that are currently missing?
- Where would those pages go?
- Do we need to revise the top-level organization of the codex to better reflect its nature as a reference for multiple audiences?
If we can come up with answers to some of these questions, we can start building stubs. That’ll give a little bit more order and structure to individuals who might want to tackle a paragraph here and there, but don’t know where to start.
Re: PHPDoc site – It appears that site is referencing BP 1.3-bleeding.
Hadn’t thought about that but would have expected PHPDoc to read from the head?
Older functions/classes would be tagged ‘deprecated’ wouldn’t they?
@boonebgorges my earlier reference to category stubs was meant to convey that idea, and I had intended to pass that by you and thought I had – probably loosing track of what I have and haven’t done but yes we could do with a document outline or expanded document outline then the stubs can be added and a guide to where and what people can contribute will be evident.
I got your drift, @hnla – I’m suggesting that you start creating that outline
Seriously, though, please do. Or anyone in this thread, please start making an outline. The rest of us can pitch in and help to clean it up. I’ll think about it tonight and if no one else starts something by tomorrow, I’ll start a new thread with some ideas.
Re: PHPDoc site -
My intention for stating that is it’s been awhile since the BP 1.2 branch was merged into BP 1.3-bleeding, so there are some functions and code missing in trunk.
Re: codex organization -
What is the purpose of the “Developer Discussions” section? Apart from the BuddyPress Forums article (which I think needs to be removed with a more, general explanation in the “Getting Started” section), isn’t that the same as the function/action reference sections?
I think we have most of the main sections already created. However, I do see a few things that need to be moved to a different section or merged.
“Changing Internal Configuration Settings” — kind of awkward to see this as a how-to because IMO, internal configuration should be highlighted more prominently
“Improving Performance” — one could debate that this is a how-to
“Make your plugin BuddyPress aware (v1.2)” + “Checking BuddyPress is Active” — need to merge these two
It is too late here to think straight so I will be looking at Codex in the morning over cups of coffee and marshaling my thoughts on how to proceed, naturally if others start the process in the meanwhile we can start comparing and fleshing the outline out; I will also tackle the troubleshooting 101 basics sketching that out offline before adding to codex.
Have begun the basics for FAQ ‘Troubleshooting 101′ but in attempting to copy it up to the codex find that there are insufficient permissions for editing and creating so have halted and post these thoughts.
My take on the structure of the FAQ page/s is running along these lines:
Main FAQ page Primary Heading = “FAQ’s” Sub Heading for main page = ” General FAQ’s”
Right menu lists a page per section that currently exists under the page ‘Specific FAQ’s’
So right menu:
- - Basic troubleshooting 101
- - Registration
- - Activity Stream
- - Extending BuddyPress
- - Stub: create new FAQ section.
This allows us to expand these specific sections as much as we think appropriate without it becoming too cluttered on one overall page.
I’ve written my FAQ in a classic FAQ style and codex allowing will place that structure up which, if approved of by consensus can be copied in skeletal fashion to stub pages under that right hand menu then someone can take a blank stub with predefined structure to edit and create a new FAQ section/page?
You must be logged in to reply to this topic.