[EthanVan]

I am trying to write documentation in the Codex library but there seems to be way too many releases flying out of the shop.

I would dedicate a lot of my time to documenting BuddyPress if I could talk you guys into slowing the roll out of new versions and working with me on the Codex. What I mean by work with me is, not making so many changes in the file names and hooks. I have been trying to nail down what hooks go with what version and it’s ridiculous.

How is a guy like me supposed to be productive helping out when the core team makes new releases month to month with changes in filenames and structuring? By next month anything I started writing in the codex will be obsolete.

My suggestion is SLOW down a minute. Wait until you have a myriad of new features and THEN make a release. OR schedule your releases to every 6 months. I can write docs pretty fast but there is no way I could keep up with the current release and change rate. I understand that once you have something cool finished you want to show the world but you’re running so fast nobody can keep up.

The codex is a far cry from what it should be so help me help you. I told you I can work on this 5 months out of the year without distraction. I’m half retired. Can you hold off on the roll out of 1.7 until I catch up with documenting what you already have? Till February maybe?

Example: I was adding to the codex for activity and noticed that the current information is way out of date and there isn’t even a file named “bp-activity.php” anymore… What is it called now? Where are the hooks written now?

Work with me and I promise I will get the documentation up to par but I need to know you aren’t going to switch everything around again in a month. I love BuddyPress but some serious QC and standardization needs to be implemented before this animal gets too big for it’s britches.

[modemlooper]

No way is the codex holding up a release. In my opinion the codex is a lost cause without a significant amount of volunteers to manage the content. It’s downright depressing and probably a turn off to people deciding if BuddyPress is the right choice.

I recently have been going over the structure and content of the WP codex and even though some of its content is lacking it is by far more helpful than what is here but like i said this codex just doesn’t have the workforce to make it what it should be. Also I feel some of the non developers in the BuddyPress community should jump in to contribute. If i had more time i would but i use my time for development not documentation. Thanks for your effort!

[EthanVan]

Well one without the other is just pointless. Hey! Lets make apple pie! It’s the best apple pie ever, but we don’t have any time to write down the recipe… That’s just illogical and so is the release of new versions of BP without documentation. It’s bad practice to say the least and will certainly contribute to the demise of BP eventually.

Let me know when someone gets serious about BP. I’ll be working on something better organized in the meanwhile. SMH

[LMJohnson]

Um… speaking about the Codex, I am trying to access the page and it is blank!

[modemlooper]

Dont get discouraged, any little bit helps.

[Anonymous User 96400]

`Wait until you have a myriad of new features and THEN make a release`

Now, that’s bad practice right there. Ever heard of release early, release often?

I agree that the codex isn’t anywhere near where it should be. But holding a release up to finish documentation shouldn’t happen.

[drill_sgt.lewis]

@ethanvan has a good point. The codex needs documentation badly. I have noticed a slowdown in plugin development and its precisely because even experienced coders have no reference. It seems like there is a select few that know how to do this. It would definitely make things better if these developers had education from documentation on the codex versus making guesses. I think there needs to be a firm initiative set with getting the codex up to par, and if people like @ethanvan are willing to devote their time to documenting the codex then the core team should welcome the effort and start a team of people who are willing to do this and send them documentation about new changes before new versions of the software is released so everything is more synchronized. I know its open source and people do this in their own time so spare me the lecture. I am about solutions, not drama! @travel-junkie it would help greatly if people learned to crawl before they walk so the philosophy you shared only holds back development because there should be more than just a gleek club of people that knows how to get around the inner workings of the software. There is strength in numbers so get the people who are the best to contribute instead of being like a hidden society.

[@mercime]

Great points raised in this thread. All are welcome to contribute to and improve the BuddyPress Codex. We can set up a BP Codex team to help audit and work on the documentation hand in hand, er, shoulder to shoulder with the BP core devs.

[modemlooper]

@mercime We had a team but it fell apart after a few weeks. I think it’s because there was no leadership. It was a do anything to help approach and that seems daunting. WordPress has loads more people on development/documentation and that is the reason this codex is behind. Just not enough people/time to get it done. We should bring this up during the dev chat.

[drill_sgt.lewis]

@modemlooper I agree with you. Everyone chipping in is not the right approach. That means you got the blind leading the blind no offense to the blind of course. Only people who know the inner workings of the software should contribute otherwise the codex will be full of blunders and misinformation. I don’t know the software as well as some but I know enough to know this is an undertaking that needs strong leadership to get this up to par. Why bring it up in a dev chat when you can do it here? There should not be a gleek club of certain people that is relevant. Closing off others is one of the reasons the codex is a mess and plugin development has slowed down. I do not mean everyone should be able to contribute because that would create a mess but the people that are the most qualified and willing to devote their time should be the ones leading otherwise I don’t see this project going much further in the future because it will only contain a gleek club of people with the same philosophies and old ideas. Its time for some fresh talent to come in with new ideas and help out if they are willing to do so! The codex is the key to acquiring this talent. A good starting point for coders will benefit the project immensely.

[Hugo Ashmore]

There have been a few attempts to kick start the codex the last not being the first. It is the case that those that have the ability and knowledge required to add accurate and worthwhile entries are also jobbing pros and time is the enemy earning a living having to take precedence on time available then any free time generally given over to development projects.

On the last attempts to organize, I tried to emphasize the need for preliminary organizing and structuring of the codex before diving in and adding (the principle of simply get stuff in there then worry about organizing is counter productive and leaves info dotted around hard to find with no one willing to the boring task of finding and moving around) imho this is still required, partly as doing so identifies what information is actually required and focusses attention and efforts.

On a somewhat contentious note there are two factors that ought to be accepted, as mentioned earlier, in reality allowing anyone to dive in and add detail is not necessarily a good idea, yes I understand the principle of general participation and how that ought to produce the fastest route to a comprehensive set of docs, but in reality it is more likely to produce or possibly produce docs with bad practise advice or just plain inaccurate advice. If this is allowed then you have to have someone checking all entries to ensure they are valid. The second point is that focus must be on dev docs, not! on beginners guides – necessarily – The need for detailed lists of all template tags, functions grouped by component, what works in the components , how to deal with same functions or function requirements outside of those components or loops, how BP works all the nav aspects, how to then modify and customize those aspects. Some of this does exist but it needs re-shaping and bringing up to date. There needs to be a top level overview that sets out the principles so the work flow is understood and which then drills down into detail.

On the above point about where discussions are held, there was and is a group, threads from last time; if the the irc dev chat isn’t the place then that group/threads should be re-animated

[drill_sgt.lewis]

@hnla You are precisely correct if we allowed everyone to contribute to the codex it would be a conglomerate of miss-information. Imagine what buddypress would be like if we just allowed anyone to contribute. Honestly I personally think it would be a nightmare. I think we need to get a team that is willing and able to work on this. Just as buddypress has a core team, we need a codex team. Not separating one from the other because they need to be synchronized and share information. Can we try to get this team rolling somehow? How do we recruit the best and most knowledgeable? They would also need a common meeting place for codex discussion so where shall it be?

[Paul Wong-Gibbs]

Thanks for your comments and interesting discussion so far. If it feels that BuddyPress is evolving quickly; great! I’d to point out some numbers about how long the last few releases took:

1.2 – 1.5 = ~18 months
1.5 – 1.6 = ~9 months
1.6 – 1.7 (what we’re building now) = ~3 months so far.

We would like to eventually have around 3 major versions of BuddyPress out every year; we need to speed up and attract new contributors to achieve this. I don’t think the frequency of releases has any direct correlation to the quality or quantity of articles on the Codex.

If anyone would like to group together and work on the codex in a co-ordinated way, we’d love that. Let us know what we can do to help.

[modemlooper]

what @hnla said plus I want to add we should use the WordPress codex as a template on how to structure the content. People are familiar with WordPress and it makes sense to display the content as such.

[@mercime]

Thanks @djpaul as @hnla noted above and @modemlooper seconded, we do need to conduct Codex audits – one from Users perspective and the other for Developer’s.

In that vein, I suggest we have leads for both Users’ and Developers section and create a new Group Forum for the BP Codex Group here e.g. https://buddypress.org/community/groups/bp-codex/. Work together on the audit, then post what pages need to be created, updated, archived, etc. and create call to action for volunteers/group members to own the page/s which can be reviewed later on. I’m willing to help lead the User’s section and also work on codex pages for Theme Development.

[EthanVan]

@Boris – Release often release fast is only good for monetized projects that have a well organized and paid team that keeps the same file structure AND hook/filter names OR has a paid and dedicated documentation team. Just because you can link to a wikipedia on your point doesn’t mean it’s correct.

When you start releasing completely different structures in each new version you ruin it for the open source community without having proper documentation. Period, no argument can be made against that fact.

@djpaul – When releases completely change the codex, yes it does have a direct correlation. Are you not seeing the drop-off in new plugins? I wonder why that is… Three releases per year is doable and the codex could catch up if you maintain the current structure and only add new hooks or filters. The whole community is struggling to get insight into the new structure.

From my perspective it appears that the core team holds themselves above documenting, as if it would belittle them. Specially after reading @modemlooper ‘s comment; “Also I feel some of the non developers in the BuddyPress community should jump in to contribute. If i had more time i would but i use my time for development not documentation. Thanks for your effort!”. That comment is dismissive at best. How do you expect non-developers to write a codex for something that you need to understand code to write? Talk about putting your foot in your mouth.

I do agree with you about structuring the BP codex based on the WP codex. Great idea @modemlooper.

The key to leadership is positive reinforcement and assurance. By having people just do whatever you create a pool of uncertainty. What this codex project needs is a leader that can assure contributors they are doing a great job and assign tasks so each contributor can say; “that’s the section I’m in charge of”.

I’m glad I sparked up this conversation, it was much needed.

[EthanVan]

I noticed that when you click on the version numbers in the current codex you get notes about the release. IMO that’s wrong. Release notes should be clearly divided into their own section. Those links should lead you to that version’s codex index. Also, I don’t think we need to have those posts showing there below the codex, not to anyone who isn’t administrating it. That just distracts people. The access to editing the codex should be restricted to the codex team. This will eliminate the possibility of vandalism or misinformation.

I wish I could restructure it, however I have no access to moving things. At least that’s the way it appears. I would copy the WP codex structure exactly and insert the information just as it is in the WP codex if I could be allowed to do so.

I’ll setup a project manager for this and we can get some real good done. Core team, do you have a place that I can setup a project manager for the codex or do you have one already? Any help in this area would be greatly appreciated. Aslo, what about getting prerelease heads-ups and notes say…two weeks before a release happens so I can make sure that the codex is updated either simultaneous to or previous to the new release?

Tasks that need to be done (for each version) are:
* List all of the hooks in a text file.
* LIst all of the filters in a text file.
* Describe all of the hooks in a text file.
* Describe all of the filters in a text file.
* Rebuild the current codex structure to mirror the WP codex.

Creating a simplified plain text based prerelease notification system that I can use to keep the codex ahead of releases would be incredibly awesome.

Example: “hook_name/function_name/filter_name” – “very brief description” [path/to/file-name.php:line#]

Codex contributors are as equally important as the core team, period. These two teams compliment each other and need to be recognized as equals by the whole community. As a contributor to the codex you ensure that plugin developers have all the information they need to provide full compatibility and more reliable plugins.

If there is something I missed PLEASE point it out to me! We need to have every duck in a row for this to be successful.

[modemlooper]

I wasn’t trying to sound dismissive. There are many users of BuddyPress that can easily contribute on the user side of documentation. My statement was in regards that my time is better spent on development of features/plugins. When I have free time I write in the codex.

[Hugo Ashmore]

erm all developers hate documenting, I loath it no one pays me to do so I always look at stuff shake my head and sigh as I realise I must document something in detail. I fully get what modemlooper means I code, anything that stops me coding, project management, tickets, writing docs etc, all things necessary to my working life I loath, an absolutely necessary evil and project management vital but I just want to make the code stuff that makes stuff happen so I can sit back and smile.

[John James Jacoby]

A few things:

Manually writing documentation about code, is an infinite loop, where no one is satisfied. Code changes quickly, line numbers change, hooks change, things get deprecated, and one becomes a bottle neck for the other.

If you want to write pages on the codex, have at it. The taxonomies can change, we can add new ones, remove ones that aren’t helpful, whatever we want. Ultimately, I picked a few taxonomies that seemed to fit the project at the time, just to have *something* since before, we literally had nothing at all.

Regarding setting up a forum for the codex we have one: https://codex.buddypress.org/team/

Regarding having longer, slower release cycles, it’s not going to happen. If anything, they’ll get smaller and faster, with less code changing more frequently.

Releases shouldn’t be held because of out-of-date documentation, and the documentation shouldn’t wait until the release. It’s a wiki for a reason, and if you’re passionate about doing the documentation labor, you’re free and able to do it. If it’s not satisfying or rewarding for you, no one expects for you to do it. Obviously, we want to create an environment that’s fun to work in, and it’s my responsibility to make sure that happens.

Regarding feeling dismissed, try to keep the negative emotions out of this. No one here wants anyone to feel bad, and the people that do work themselves out. Reread for tone and clarity, and understand that we’re all passionate, and just want to do good things together.

Codex contributors are not more or less important than anyone else, but the BuddyPress Core team is going to make the decisions about code changes and release cycles, and that won’t likely ever change.

The fact is, that documenting an open-source project is neither glamorous nor sexy, an it’s easy to feel like you’re efforts are not appreciated. That last part’s not true, but since there’s no obvious or advertised audit trail, and no reward system in place, people working on the codex are often separated and in the dark about what’s going on around them.

If you want to keep up, you just have to try harder; no one is going to slow down for anyone else. As an example, I’m often in the dark about what’s going on in WordPress core, so I spend an extra 2 hours every night reading through the changelog, testing BuddyPress against WordPress trunk, and generally just spend more time doing more labor. It sucks, but I can’t ask them to slow down production and put their initiatives on hold.

It’s ironic y’all want to move towards the way the WordPress codex; many of their documenters strongly dislike Mediawiki for this purpose, and want to move towards a WordPress based approach like we have here.

Anyways, this is all good and healthy debate, but in the end it comes down to earning the right to have your opinion carry more weight than someone else’s, the old “meritocracy” approach. “Assigning a project manager” isn’t how this works. It’s an open system where everyone volunteers their efforts, and if you volunteer a higher quality of work more efficiently, you win the game and get to start making decisions.

Regarding having ducks in rows, ducks organize themselves into the pattern that suits them best at the time. It’s great to want to lead the pack, but you don’t self-appoint in an established and mature project.

Metaphors and responses aside, what 1 thing can I do immediately to improve the codex experience? Let’s pick 1, and talk about it, and make a decision on what to do about it.

[Hugo Ashmore]

However @ethanvan can we keep things on site please not off on private emails, we have already a group or thread on codex matters lets try and keep focussed there.

I agree about the sentiments re attempting to mirror WP codex as much as possible.

We don’t simply want a long list of hooks/filters though we have a complexity of functions that need describing , also we need to explain the basics of how BP works in terms of navigation, core templating etc it’s not straightforward and not strictly in keeping with WP we need examples of how to create new nav items, update and improve examples of the primary loops, group extension etc

[drill_sgt.lewis]

@hnla point taken but no one is paying the core development team either so why is their no initiative set for codex documentation? If there are people willing to take their time to create free software then why is there none to document the codex? I could see a huge leap forward in development if these up and coming coders have the vital documentation that would allow them to produce quality features and plugins.
Edit:
My point is simply give people the documentation they need to participate. There is strength in numbers and when you have a slew of educated coders at your disposal then anything could be achieved within this project. Its basically allowing us to help you. If we do not have the keys to do this, I could see this project reaching a plateau and future development ceasing!

[Hugo Ashmore]

The answer to those questions was touched upon by JohnJames earlier, a few posts up.

I would love to see really good docs, but it’ a tough challenge, and as said ‘not sexy’ and although rewards not really the point scant recognition for ones efforts, were you aware I contributed one particular page took me almost a day to do it well, testing each point to make sure it was accurate, some ten revisions later by various people and I may as well have not bothered, was it improved ? debatable but probably, that I added the detail to start with more the point ? perhaps, not really sure though so you see one of the issues

[modemlooper]

Going over that team link which I had totally forgot about. Some good info. I am moving this thread over there. I have a suggestion to get it rolling. https://codex.buddypress.org/team/

[John James Jacoby]

My point is simply give people the documentation they need to participate.

Is there something preventing you from doing this that I can help with?

The “if you don’t do %, you’re going to lose %” attitude isn’t a great motivator; it’s leading with fear, which isn’t how I choose to lead my projects. Future development will cease when the project is no longer relevant; that will be a sad day, but it isn’t anytime soon. BuddyPress is as strong of a project as it’s ever been, so worrying about it’s future is wasteful.

[EthanVan]

I didn’t realize that MediaWiki powered the WP codex… I quite like the WP powered codex idea I just meant that the BP codex should be organized like it is at WP.

@johnjamesjacoby – It’s already been admitted that the last attempt at the codex was a fail due to lack of leadership and everyone just doing whatever… So keeping that mentality is futile and is holding back the success of the codex. I’m not here to kiss butt and brown nose. I’m here to do a job that I won’t get paid for that will help YOU and YOUR project immensely because it needs to be done. Don’t get righteous about “earning the right” to be a leader of the codex team when your plan is not to have one.

Someone should take the reigns and build a structured codex team and I see no other person stepping up except myself. I expect that I should be allowed this privilege solely on the basis that I am willing to do so, and additionally, have many years of leadership experience. If I fail, you lose nothing and get to have a laugh at me, but if I succeed, the amount of praise and respect BP will gain will be immeasurable.

So, please let us put our pride away for a minute, stop addressing leadership rights, and concentrate on organizing a codex team and getting it structured in a way that lends itself to productivity and direction.

I agree with you @hnla we need to stay focused. I realize we need to have a deeper scope within the codex. What I think should happen first though is building the lists and descriptions of functions, hooks and filters, the reference. Then we have a base page for everything. Later we can go into deeper coverage and provide example code etc.. Any project this large needs to be completed in phases.

@modemlooper, @johnjamesjacoby, I don’t feel dismissed, the codex was being dismissed. Anyways, that’s going to change.

The very, very first thing I think should happen is setting up a clean slate to build on. Keep the codex up as is for now but give me a new, private, clean slate to create version indexes and add pages for each function, filter and hook. We can point to the new codex when phase one is complete. The reason I want to use pages is so I can implement a parented structure. Are there any objections to this? Any other ideas? Anyone wanna slap me?