Jason Rouet 10:10 am on September 7, 2023
Tags: docs-chat ( 79 ), summary ( 141 )

BP Docs-Chat summary: September 6, 2023

In attendance: @jasonrouet @dcavins @im4th @bouncingsprout @vapvarun
Slack archive
FYI: here’s the agenda we published before the meeting.

Here’s the recap of the BP Docs-Chat on Slack:

1. Follow-up on the actions planned for August

Starting a discussion with @johnjamesjacoby on how to add a warning message on the codex

-> See last docs-chat summary for more details.

@im4th said he’ll reach out to JJJ about this item (nothing urgent).

Deploying the tutorial on how to contribute to the new doc directly on Github

@im4th committed it to trunk here: https://github.com/buddypress/buddypress/tree/master/docs/contributor/documentation

As we said during the previous meeting, this PR is kind of a tutorial on its own, as it initiates subdirectories and shows what content might look like on Github.

Quick news: how are things going for 12.0.0?

@im4th said beta testers are still needed. 12.0.0-beta2 will probably be packaged on September 7.

For now, the documentation team isn’t ready to manage release notes on the new documentation. But it’s an opportunity to think about how we’ll document everything a release adds/removes/changes in the future.

The 12.0.0 release should help us identify the process to be implemented for the documentation team to update the content once the release notes are generated.

@vapvarun shared with us how release notes are generated. When 10.0 and 11.0 were released, the following plugin, built by @rayisme was used to generate release notes: https://github.com/r-a-y/bp-changelog

@im4th and @bouncingsprout quickly said it would be great to improve it to handle markdown formatting and maybe add some github action.

2. Main item of our meeting: how to start working on the content over the next two weeks:

The plan discussed is:

@im4th will share a csv file listing all the existing content urls from the codev to @jasonrouet who’ll create a spreadsheet on GDrive for the team to work on it easily,
once the spreadsheet shared with the team, people will be able to:
- review: we’ll need @im4th and @dcavins help specifically to comment each urls by saying if:
  - the content is up-to-date (maybe it needs more details, but could be imported as is to the new doc)
  - the content needs editing (some parts of the content change but it’s still a relevant piece of content)
  - the content is totally outdated and should be rewritten from scratch (some pages could still be needs, others not anymore if it refers to some feature that doesn’t exist at all)
  - edit: once a url has been reviewed by someone with enough experience, it will be ready for assignment. Someone will then be able to take charge of editing the content (see tutorial on how to contribute to the doc for the steps).
Alongside, the work on the importing the content from the codex. We’ll have to reconsider how the content is structured. At first we’ll probably start with something close to the current codex structure and then progressively reorganise things based on the updated content.

So basically, the “reviewers” (a.k.a our gatekeepers as @bouncingsprout named them 😀 ) will add some kind of ‘inline comment’ on the spreadsheet. It will help “editors” know what to remove/amend/rewrite.

The initial work on sorting/importing content from the codex once done, we’ll be able to say “we are done with the codex, everything still up to date on the old documentation is already in the new documentation” and focus on producing new content that doesn’t exist on the codex (edited)

Starting by sorting/editing and importing the articles of the codex, we will quickly be able to ensure that what is still up-to-date in the codex is also already available in the new documentation (with updated screenshots, references to the latest versions, etc.). Then we’ll be able to focus on producing new content for the new documentation without having to care about the codex at all (with one exception: the release notes will still be published via the codex for now).

3. Language quality check: how can we ensure that the documentation is written in proper English? Is en-US the default language localisation?

Intro: it’s best to adopt good habits from the start. A significant part of the team won’t be English natives.

The group agreed on having en-US as the default language. Quick note from @jasonrouet: remember to set your tools like Deepl/Grammarly/LanguageTools/… to that specific locale! 😉

We said, language check (spelling/punctuation/grammar) should be part of the quality checks at the same level as Markdown formatting check, technical content check…

For now, Ben and David agreed to check the language. We’ll document this process in /master/docs/contributor/documentation/.

4. Get inspiration from what the WordPress project documentation team is doing

@bouncingsprout said he’ll introduce himself and attend some meetings from that team to collect good practices. Ben said they have a good new contributor onboarding process, internal team processes, etc… All good for the team, any external advice is welcome, we need our own processes, but learning from the team that has been working for years and that has already carried out a migration from their old codex to a new documentation is certainly worthwhile.

Finally, he said he’ll be our cookie dealer, copying @milanacap strategy! 🍪 See you at a WordCamp to share a snack together! 😉

Next Docs-Chat

It will happen on September 20 at 19:00 UTC in #BuddyPress. We are a small but friendly team, everyone is welcome to contribute: this may be done by editing the documentation or by sending us feedback on what is missing from the documentation.

#docs-chat, #summary

Jason Rouet 9:42 am on September 6, 2023
Tags: Agenda ( 188 ), contribution ( 4 ), docs-chat ( 79 )

BP Docs Chat Agenda: September 6, 2023

FYI: BuddyPress Documentation Chat is taking place on Slack on a regular bi-weekly frequency. Everyone is welcome, the discussion is expected to last one hour. If you have any questions, please contact @jasonrouet on Slack.

After a few preliminary discussions about the aims of the new documentation, how to contribute to it via Github and what to do with the current codex, we’re now starting to focus on sorting the old content, assigning the first tasks and contributing to the new documentation.

Please join us on September 6 at 19:00 UTC (Wednesday) in #BuddyPress, here’s our agenda:

Follow-up on previous actions
Focus for the next weeks:
- Sort the content from the codex (the PDF generated by @imath will be helpful).
- Work on the new documentation structure.
- Start assigning content to be edited/imported/created and initiate PRs.
Undiscussed items from the last agenda:
- How do we want the new Documentation to be friendly for end-users and also for developers?
  - Also, how will the Documentation be split between the use and developer subdomains?
  - How will one Documentation communicate to the other on specific topics?
  - What will be the process for choosing which documentation should be prioritised? (This should maybe be a recurring item of our Doc-Chat meeting?)
- Language quality check: how can we ensure that the documentation is written in proper English? Is en-US the default language localisation?
- Is our workflow similar to that of the WP Documentation Team? If we are creating docs differently, how and why? How can we learn from what our colleagues in this team are doing? Is it a good idea to move towards the same workflow? (@bouncingsprout offers to be the link to the WP docs team, to try and get some best practice and their guidance?)

Let’s have a friendly and efficient meeting! See you 🤗

#agenda, #contribution, #docs-chat

Jason Rouet 9:42 am on September 6, 2023
Tags: docs-chat ( 79 ), summary ( 141 )

BP Docs-Chat summary: July 26, 2023

In attendance: @jasonrouet @dcavins @im4th
Slack archive

Quick note: I was largely afk in August, I was on summer holiday + sick for a week and when I went back to work I had a lot on my plate. I’ll do my best to publish the summaries as quickly as possible from now on. 💪

FYI: here’s the agenda we published before the meeting.

As the agenda was quite long, we didn’t have time to discuss all the items, so we have covered the main issues. Here’s the recap of the BP Docs-Chat on Slack:

1. Discussion about how to host @imath tutorial published on the previous BP Docs-Chat summary + extra discussion about the future documentation structure

Props from @jasonrouet about @imath work, it’s fantastic and it will help new contributors (and even existing ones) dive into the new documentation on Github.

As for now, the tutorial only have been published on the bpdevel.wordpress.com website. It has to be available on the Github repo directly with further information about how to contribute to the BuddyPress project globally and to documentation specifically.

To do so, we discussed the /docs subdirectory and the needs to improve the folder structure. On the BP repo, we already have a /docs/ subdirectory where all the documentation will be added. Then we’ll have to polish the structure like this:

– /docs/user/ with all resources on how end-users can use BP
– /docs/dev/ with all technical resources for devs to learn how BP works
– /docs/contributor/ with all resources on how to contribute to the BP project

We discussed the /doc/contributor/ structure and said it could be organised like this:

/docs/contributor/
/docs/contributor/code/ with resources on how to contribute to BP codebase
/docs/contributor/documentation/ with resources on how to contribute to BP documentation
/docs/contributor/translation/ with resources on how to translate BP

@imath said he’ll move the tutorial to /docs/contributor/documentation and improve it with the latest screenshots he made.

To improve the tutorial, @bouncingsprout suggested starting a visual presentation (maybe a flowchart?) of the steps involved in the process to help people understand how to contribute. We all agree it could be useful to people who aren’t used to Github.

2. What to keep from the existing Documentation structure/content? Where to start building the new documentation?

@jasonrouet started the discussion by suggesting importing the contents of the existing documentation (the codex), then sorting out what is no longer up to date, what needs to be updated and what can be kept as it is still up-to-date. The aim would be to start from the existing content, rearrange it and then add new content.

@imath and @dcavins said the actual documentation is very outdated, screenshots need to be updated and shouldn’t be imported as is.

@im4th shared a PDF file listing all the existing content from the codex:

buddypress-codex Download

Rather than importing the actual content from the codex as is. It was suggested to think about the structure and what kind of content will be added to the documentation and then pick interesting information from the codex after checking it is still accurate.

@im4th said the team tried to update the codex at the beginning of the year but gave up as it was very deprecated and is suggesting starting from scratch rather than loosing too much time and energy starting from the existing content. Here’s a link to the result of the previous attempt to update the codex for the record.

At this point in the discussion, it seemed clear that the codex is kind of frozen and to be kept as an archive for users of previous versions of BP.

Moreover, let’s keep in mind that the release notes are also part of the documentation. We’ll have to rediscuss how to link the release notes with the rest of the documentation (e.g how release notes can help identify what part of the documentation needs updates).

So here’s our initial process idea:

have a look at the codex structure as an example to build the structure of the new documentation but we won’t rely on it at all for the content,
based on the PDF file, tag the content: “very outdated” for content that will not be imported, “need update” for content that could be imported after edition and “up to date” for content that can be added as is,
once done, contributors will be able to assign themselves the content to update, create, import and start PRs.

How to document BuddyPress efficiently in a structured way is something we’ll learn and adapt over time.

BP Docs Chat Agenda: July 26, 2023

The current focus is on starting a new Documentation and organising the team effort. Please note that we have a packed agenda this week as this is our first proper meeting, so we won’t have enough time to cover everything and will focus on the codex import and initial actions. Any remaining items will be discussed async or at the next meeting.

Please join us on July 26 at 19:00 UTC (Wednesday) in #BuddyPress, here’s our agenda:

The first version of the new documentation contribution tutorial via Github had been published by @imath on the previous BP Docs-Chat summary:
- First, it has to be properly documented on Github! 🤓
- Then, @bouncingsprout suggested expanding it: adding a visual presentation (a flowchart?) highlighting the process from when a documenter logs in to GitHub for the first time, how to fork the repo, work on the forked version and then prepare a PR and then who is reviewing and accepting the PRs.
- Additionally, once the website will be ready to host the new documentation: we’ll have to include the steps that lead to the documentation being published from the Github repository to the official website.
Starting the new documentation:
- How to import properly the current content from codex.buddypress.org to the Github repo (by properly, I mean checking that the formatting is in Markdown once the content has been imported).
- Sorting and ordering the content imported from the Codex: what content is up-to-date, to be updated or out of date/to be removed?
- Once the old content is sorted and ordered, we’ll have to think about the structure and start producing new content/update content imported from the codex.
Documentation coordination and workflow:
- Who will approve the PRs on Github besides BP core committers? Could the Documentation team lead have sufficient permissions? Can we plan a quick training?
- How to coordinate with the core team about new releases: tracking changes, addition… Case study: version 12.0.0 is about to be officially released, how to track changes and document it?
- How do we want the new Documentation to be friendly for end-users and also for developers?
  - Also, how will the Documentation be split between the use and developer subdomains?
  - How will one Documentation communicate to the other on specific topics?
  - What will be the process for choosing which documentation should be prioritised? (This should maybe be a recurring item of our Doc-Chat meeting?)
- Language quality check: how can we ensure that the documentation is written in proper English? Is en-US the default language localisation?
Misc
- Is our workflow similar to that of the WP Documentation Team? If we are creating docs differently, how and why? How can we learn from what our colleagues in this team are doing? Is it a good idea to move towards the same workflow? (@bouncingsprout offers to be the link to the WP docs team, to try and get some best practice and their guidance?)
- What would be a reasonable plan for retiring the current Codex and publishing the new Documentation? No rush, but a deadline (even a vague one) might help to keep us motivated.

We don’t have cookies (yet), but let’s have a friendly and efficient meeting! See you tomorrow 🤗

Props to @bouncingsprout and @im4th for adding their ideas and for reviewing this post.

#agenda, #contribution, #docs-chat

im4th 8:34 am on July 24, 2023
Tags: docs-chat ( 79 ), summary ( 141 )

BP Docs-Chat summary: July 12, 2023

In attendance: @jasonrouet @bouncingsprout @im4th
Slack archive

The BuddyPress project is very happy to welcome Jason Rouet (@jasonrouet) as our new Documentation leader & Ben Roberts (@bouncingsprout) as a Documentation deputy.

Where are next BuddyPress Docs?

BuddyPress Docs are primarily directly available from the main BuddyPress SVN repository. We’ve created a docs directory which contains 2 sub-directories: 1 for the « developer » documentation & the other for the « user » one.

As each commit on our SVN repository is synced with our GitHub repository, documentation is also available there and we’ll be able to enjoy GitHub browsing service to improve the reading experience.

If GitHub can be intimidating for the uninitiated, using it from our BuddyPress GitHub repository has interesting benefits:

We don’t need to wait to put up documentation sites: we can start contributing right away (and we actually started!)
When committing a new Documentation contribution, we can credit authors so that they are rewarded with a lovely BuddyPress contributor badge on their WordPress profile.
As explained into our last feedback post: having docs directly inside our repository shows we acknowledge Documentation is as important as code.

Once we’ll be satisfied with the docs content, we’ll always be able to use the WordPress handbook plugin to synchronize it with a BuddyPress.org Network site, or better to browse documentation directly from the WordPress dashboard of the site BuddyPress is activated on.

How to contribute to BuddyPress Docs?

The first steps a contributor needs to accomplish once are (everything remains totally free):

Create a WordPress.org account & eventually link it to the WordPress.org’s slack to attend Docs Chat.
Sign up a GitHub account
Fork the BuddyPress GitHub repository into their GitHub repositories

For each contribution & from contributor’s forked repository:

Create a new branch (from the command line or directly from GitHub website)
Write in Markdown the documentation resource inside the user or developer docs sub-directory (using a text editor or directly from GitHub website) & commit locally the changes.
From the created branch, pull a request to the BuddyPress repository to merge the changes (from the command line or directly from GitHub website).
Update the branch if a BP Team member asks for changes after their review.
Ask @jasonrouet or @bouncingsprout for help if needed!

Once a Pull Request is validated by a member of the BuddyPress team, a BP Core Committer will include the changes to the BuddyPress SVN repository so that they will be synchronized with the BuddyPress GitHub repository (It’s very important PR are not merged from the BuddyPress GitHub repository). At this point, contributors will need to synchronize the main branch of their fork (master) with the BuddyPress GitHub repository. This synchronization can be achieved before building a new contribution (Step 1 of the above list).

Who are the first members of the Documentation team?

During the chat, @bouncingsprout and @im4th (both developers) shared the same intuition: it’s best to have a Documentation leader that is not a developer. Developers are always attracted by code & we need to put the focus on end-users instead. @im4th also shared what he thinks are important tasks the Documentation leader needs to accomplish:

Lead the BP docs-chat
Fix priorities
Review contributions (PR)
Everything the leader thinks is important to do!

@jasonrouet seemed the best candidate of us 3 to lead the Documentation team. If he felt a bit « trapped » at the beginning, he finally volunteered for the role & @bouncingsprout also did so as a deputy.

@dcavins & @im4th from the development team will also contribute to docs and all code contributors are invited to do so. Contributing to docs is a good way to improve code, for instance @im4th lately opened/patched a few tickets after writing some documentation contributions (See #8932 & #8933).

Support contributors are also strongly encouraged to contribute to docs and attend Docs Chats.

More globally every BP user is very welcome to give a hand, as @jasonrouet said: completely reorganizing the BP Documentation is a huge challenge & we’ll need more motivated people around to progress quickly.

We’ll start us 4 because we absolutely need to improve Documentation and prepare the important change about URL Parsing we’re introducing in BuddyPress 12.0. We are confident new contributors will be attracted by the first improvements we’ll add ourselves.

As @jasonrouet suggested, once there will be more contributors to docs, we’ll be able to share leading tasks between several volunteers.

When do we meet & how regularly?

Here’s @jasonrouet first decision! BuddyPress docs-chat will happen every other Wednesdays at 19:00 UTC.

Next Docs-Chat

It will happen on July 26 at 19:00 UTC in #BuddyPress. If you have specific points or ideas you want to discuss about, don’t hesitate to share them in comments.

#docs-chat, #summary

BP Team Updates

Follow BuddyPress development & documentation latest news

Archives

BP Docs-Chat summary: September 6, 2023

1. Follow-up on the actions planned for August

2. Main item of our meeting: how to start working on the content over the next two weeks:

3. Language quality check: how can we ensure that the documentation is written in proper English? Is en-US the default language localisation?

4. Get inspiration from what the WordPress project documentation team is doing

Next Docs-Chat

BP Docs Chat Agenda: September 6, 2023

BP Docs-Chat summary: July 26, 2023

1. Discussion about how to host @imath tutorial published on the previous BP Docs-Chat summary + extra discussion about the future documentation structure

2. What to keep from the existing Documentation structure/content? Where to start building the new documentation?

Other lower-priority topics discussed.

BP Docs Chat Agenda: July 26, 2023

BP Docs-Chat summary: July 12, 2023

Where are next BuddyPress Docs?

How to contribute to BuddyPress Docs?

Who are the first members of the Documentation team?

When do we meet & how regularly?

Next Docs-Chat