Hi, On 12/16/2009 2:58 PM, Sergiu Dumitriu wrote:
On 12/15/2009 09:35 AM, Vincent Massol wrote:
Hi,
We need to decide how we want to document xwiki.org with regards to project versions and skins. For example the screenshot and features described can depend on 2 factors: - the project version (XE version for ex) - the skin used
Project versions =============
We have several choices: 1) We make the doc only for the latest version and in this case we should probably export the pages at release time and make it available as a zipped HTML export so that people using the older version can refer to them. 2) We make the doc work the last 2 releases. That would be either 2.1 and 2.0.5 or 2.2M1 and 2.1 depending on how we view it and depending on whether we want to document on xwiki.org before we release or not.
Isn't the documentation for older version available in the document history? Can't we just: - save with a "Documentation for XE 1.9" comment before starting to update the documentation, so that we can easily identify which document Wouldn't it be hard to monitor all this comments for different apps/products?
version applies to which product version - (optional) add a list of older versions in the document pointing to the right version from the history
I think you are suggesting what Microsoft is doing with msdn. Eg: http://msdn.microsoft.com/en-us/library/system.io.file.aspx A simple implementation would require: - a basic wiki macro containing: - application/product name - list of older versions + links to other pages or older versions of the same page - manually updating the macro data when updating documentation(Should be quite friendly with the new wysiwyg) - (optional?) a script which updates all non-modified documentation pages of the product on the product release. The cost is probably a bit higher then solution (1), but not by much. Thanks, Florin Ciubotaru
Personally I think I prefer option 1 with a little addition: - whenever something that is new to the last release is documented, we should add a little "New" logo (possibly with the version value, "New in 2.2" for example). This could be done with a wiki macro.
If option 1 is chosen then we need to add a step to the release process.
Skins ====
Again we have several choices: 1) Document only for the latest skin 2) Document for all supported skins. Right now that would be Toucan + Colibri (not sure about Albatross, I don't think we've officially said it wasn't supported).
If we were to do 2) then this that for example this page http://code.xwiki.org/xwiki/bin/view/Applications/WatchlistApplication would need to contain screenshots for all supported skins *OR* there should be different screenshots only when the skins have different features. This is the case here since the location of menus and actions are quite different.
I'm hesitating more for this one... 1) is definitely easier for us so I'm tempted to propose 1) but with the proviso that we make it clear in the text when a feature is available only for a given skin (for ex: the Show Code menu action is avail in Colibri but not in Toucan).
I think we should document for all supported skins, but only when the feature is different between the skins, not just on the aspect (colors), but in placement, naming or functionality.
WDYT?
When we agree we should put the result on dev.xwiki.org in a new page describing how xwiki.org is documented.
Thanks -Vincent