What started as an utopic idea has now become real! Over the last Plone releases, the documentation had become sadly outdated, because the people writing code for the new features of the product were faster than the people writing the documentation for them.
During the last Plone Conference the Plone Documentation Team was revived. It was time to start doing things The Right Way (TM). Our idea was to bind the development to the documentation, studying PLIPs after being approved by the Framework Team and updating and extending the documentation base accordingly before the new product version is released.
And finally, we did it for 3.3! So congrats to everybody who’s participated! I hope that in the future more people will chime in and we will improve our workflow for updating and testing changes in the documentation. Some ideas:
- We can’t publish (make visible to everybody) the documentation for the new version before the new version is released, because it will confuse people. Next PHC version will likely provide us Working Copy Support so we will be able to edit documentation “privately” while keeping the old (stable) version of a page public.
- We have to coordinate better with the PLIP implementors to write, review and verify the documentation. Proposed workflow:
- Make a list of affected docs. This list will likely include only documents in the official documentation area.
- Make a copy of them and find someone to document the changes. With Working Copy Support, thiw will no longer be neccessary.
- Ask the implementer of each PLIP to review the introduced documentation changes. Test them against a beta or release candidate release.
- After the final release, copy the contents of the copied articles back to the live ones, and delete the copies. With Working Copy Support, promote the changes to the public page.
Happy ploning to everybody!