Ok, I’ll make a brief post regarding the documentation section and navigation in general so we can start discussing those areas.

The documentations section have a few issues and I think the main issue is that it does not have a uniform navigation. By that I mean that depending on where I end up in the codex, I get different sidebars with different content. This confuses the hell out of me, especially since the very anonymous breadcrumb always refer back to the codex home and do not show me where I am in the hierarchy of things.

To make this easier there should be one sidebar for all areas of the codex along with a search function.

The related links is confusing as well as they do not seem to have any connection to the topic or page I am at. Instead they seem to be a bunch of topics in the codex in general or perhaps from a specific section/category? Either way if I want to learn more about bbp_forum_post_count I don’t think it’s very likely that a topic about bbp_breadcrumb will improve my experience. These should be removed from the sidebar and added in context with the content and as part of the sidebar navigation hierarchy.

One other thing I find strange is that neither of these pages have discussions, either in the form of comments or to a dedicated thread on the forum. By not having that it’s more difficult for the users to express if the information is confusing and lacking in some way. Essentially the content becomes dead and will most likely see very little in the form of improvement.

When it comes to navigation in general I still find it strange that there are no breadcrumbs below the main navigation. A lot of people will end up on different pages when they enter the website and regardless of where you end up you should always know the context the page you are visiting in relation to the overall navigation, especially on a website with so much content that is spread out in different sections.

I also think that the main navigation look vague and while I appreciate the little bee image it does not help with the visibility of the navigation. I first thought something was wrong with my screen since I noticed the figures that looks superimposed until i realized it’s just a background image. I would say keep the bee, but remove the white traces and the background image, then make the fonts larger for the navigation.

The navigation itself seem to not be in order with what I would suspect people are looking for. I might be wrong, but I doubt people come here looking for the blog before support or that downloads are the least sought feature? It would make more sense to have support right after “about” and depending on how you want downloads to be handled it would either be the most important item so it would be added last with the CTA or as the second navigation after about.

..and i’ll just end with a question regarding the about page: do you really feel that the categories in the sidebar is a good representation on what you have written in this section? It looks a bit strange that you have items such as “i18n” in the category of the about us and then you have added an inline content box with the actual content of the about section. I would love to hear the meeting where that was decided and the discussions on how that would make it easier for the visitor to find relevant information about BBPress 😉

[@netweb Keymaster 10 years, 4 months ago]

Cool, thanks for kicking this off 🙂

Lets start with the layout structure and a “Table of Contents”, I added these recently and these are a good place to start and closely match not just the BuddyPress Codex layout guides but also much of WordPress also (Links to these below).

Getting Started, Theme Development ,Plugin Development, Participate & Contribute and Developer Resources

The Codex is now fully setup with an ‘Automated Table of Contents’ sidebar, see this section on how to acheive this, also the “breadcrumb” will also ‘sync’ up with this table of contents structure.

For now ignore the ‘related posts’, these should also update based on the table of contents plus we are going to move the functions from their current location in the codex, I’ll detail those plans later.

Links to topics on the forums for each section/page of the codex is a great idea, we can do this fairly easily. 🙂

The ‘About’ page is part of the blog, the categories are the categories of the blog posts on the site and this is an automatically generated list, same with tags. Also many of the visible (and there are many not visible) of links from the ‘About’ page is from before we had the codex setup, thus much of the content throughout those links is either duplicated or redundant. A third set of duplicated content is our Trac home page https://bbpress.trac.wordpress.org that we need to redo and sync up with the same content (or at least links) to the correct content on the bbPress codex. A fourth location will be the actual source code of bbPress which primarily is on the plugin homepage https://wordpress.org/plugins/bbpress/. The fifth source would be basically identical to the fourth though is contained in a separate file and that will be for the plugin homepage on GitHub https://github.com/bbpress/bbpress.

BuddyPress has a Google Docs “Table of Contents” here and I have just forked and edited that spreadsheet for us here on bbPress. I have set the permissions so anyone with this link can edit the spreadsheet, with some luck it won’t be vandalised, if this happens we can change this setting to “edit only” for verified editors.

Before we change any of the existing URL’s for documents in the codex (e.g. Moving the FAQ into the “Getting Started” section) we will need to make some redirects behind the scenes so existing links will be forwarded to the new links.

A good place to start would be extracting the sections from the awesome guides Robin has already contributed to build up our “Table of Contents” and once we are happy with what we have for starters in the “Table of Contents” we can then start updating the actual codex pages.

A few references where we can reuse content and build up our table of contents can be found throughout existing WordPress and BuddyPress projects:

BuddyPress Codex

https://make.wordpress.org/core/handbook/
https://make.wordpress.org/support/handbook/
https://make.wordpress.org/docs/tag/handbooks/

Project Status