Page MenuHome

Blender Documentation Release Cycle
Open, Confirmed, MediumPublic

Description

Blender Documentation Release Cycle

The Blender Documentation Project follows Blender’s main development cycle, which is documented here (https://wiki.blender.org/wiki/Process/Release_Cycle).
In essence, the development process is broken down into 5 defined steps. Each step is called “BCon” followed by a number.
Each development step has its own goals and tasks that should be followed as follows:

BCon 1

Duration: 2-3 Weeks

  • General polishing of existing docs
  • Begin any larger standing tasks
  • Document changes made to Blender’s master

BCon 2

Duration: 3-4 Weeks

  • Focus most of development on writing documentation for features already added or likely to be added to Blender before the next release.
  • Finish any larger tasks

BCon 3

Duration: 2-3 Weeks

  • All focus should be on documenting new features
  • The SVN repository should be kept mostly stable, meaning refraining from moving/renaming files

BCon 4

Duration: 1-2 Weeks

  • Focus on polishing existing documentation
  • All features at this point should already be documented
  • The SVN repository should be kept stable, meaning no moving/renaming files

BCon 5

Duration: 1-2 Days

  • Add any finishing touches
  • Get everything ready for the release date

Details

Type
Design

Event Timeline

Aaron Carlisle (Blendify) triaged this task as Confirmed, Medium priority.

The goal of this task is to make comments on my proposed process and work on implementing this into the documentation workflow along with the Blender development process.

I think this makes the stages too specific. I would aim for the minimum amount of restrictions you can have, keeping just the ones that serve an important purpose.

Big and disruptive changes need some time to finish, so doing those only up to the end of Bcon 2 makes sense. The reason behind rules regarding moving/renaming are not obvious to me though. Maybe it's for translations, but I would think all text changes should be restricted then?

Aiming for all new features to be documented by the end of BCon 3 seems good.

As far as what should be focused on, it's a bit difficult to control. If some contributor wants to focus on polishing existing docs, I think they should be able to do that through all stages as long as it's not too disruptive. The proposal is not clear on that. If someone is responsible for documenting a new feature, they should focus on that in time to meet the deadlines, but it's not a rule for the entire team I think.

For me the important things are:

Bcon 1 & 2:

  • Repository open for all changes.
  • All big or disruptive changes must be finished at the end of this stage.

Bcon 3:

  • Repository open for additions and other incremental improvements.
  • All new Blender features should be documented by the end of this stage.

Bcon 4 & 5:

  • Repository open for additions and other incremental improvements.
  • Documentation should be polished for release by the end of this stage.

I think this makes the stages too specific. I would aim for the minimum amount of restrictions you can have, keeping just the ones that serve an important purpose.

This sounds good and I like the generality of the restrictions you proposed.

The reason behind rules regarding moving/renaming are not obvious to me though. Maybe it's for translations, but I would think all text changes should be restricted then?

This serves two purposes, one like you said for translations so po files are not being moved around and text getting marked as fuzzy just because of moves.
The other reason is to preserve links, by this time we don't want links to new documentation from outside sources to go stale.

As far as what should be focused on, it's a bit difficult to control. If some contributor wants to focus on polishing existing docs, I think they should be able to do that through all stages as long as it's not too disruptive. The proposal is not clear on that. If someone is responsible for documenting a new feature, they should focus on that in time to meet the deadlines, but it's not a rule for the entire team I think.

This also sounds good, we can word the release cycle to encourage any contributions at anytime while stating core writers/developers should focus on new features.