As is already known, the XWiki documentation is being refactored according to new agreed-upon guidelines. The Documentation Guide is also being updated to reflect these changes.
Some sections and practices have become outdated or incompatible with the new approach:
In the Macros section: the use of info and warning macros is no longer promoted, as the FAQ section is now recommended for small troubleshooting items. (See Proposal 11: Heading structure for Doc Pages ). In addition, the toc macro is automatically implemented when the DocumentationXClass is attached, so it no longer needs to be included in the guide.
In the Text Editing section: the sentence “Use bold to emphasize important pieces of text” is proposed for retraction, as it contradicts the No Styles rule.
The content in the Preview and Save section is only suitable for “Minor Changes”, since Change Requests are now mandatory (Edit: Change Requests are recommended, not mandatory for major edits.) for major updates and do not allow previewing. It is therefore proposed that this content is moved under the Minor Changes section.
The Moving a Page section should be reworked to describe the correct process for moving either a section or the full content of a page. The process should cover grouping both pages in a Change Request, checking for backlinks, and using the old page to redirect to the new section/page.
Note that bold is not just a style, it can also contain a standard meaning: important elements set in <strong> tags are almost always bold. Instead of using hard-coded styles like shown in the nostyle rule example, to add a strong tag you can just use XWiki syntax.
I’m -1 on this one, usage of bold goes beyond style and the reason you gave is not enough to stop using bold altogether.
If we prevent using bold style but encourage strong tag syntax, I’d agree, but since the difference is far from being easy, I doubt it’d be a relevant strategy
For reference:
+0, it definitely needs to be reworked but I’m not sure what would be the best solution
Where did we agree to make CR mandatory for major updates? (I don 't recall discussing that). Also, even if it were agreed, how do you ensure it?
I’d be -1 to make it mandatory since that’s too just too painful and makes writing documentation so much harder. We could recommend using CR, especially if the writer is not sure about what’s being written but I wouldn’t make it mandatory.
Also, CR does allow previewing since it has a “Rendered content” tab.
It’s possible there was some misunderstanding on my side. I was under the impression that contributors would need to use Change Requests for updating documentation. Indeed, using CRs is not mandatory, and it is not prevented to simply save the changes without a CR. I will mark an edit in the proposal that using CRs is recommended but not mandatory. Thanks!
As Lucas said, bold text is important. I think it would be ok if you wanted to encourage not using it for the sake of consistency, but it shouldn’t be entirely forbidden.
Thanks!
We don’t intend to ban the use of bold. In the existing documentation (outside the new location) there are places where bold has been used and others where it hasn’t. We don’t want to add a rule like “don’t use bold” or “bold is forbidden”. We just don’t want to encourage it in the doc guide.
Using bold in documentation is not restricted, nor encouraged, in the doc guide.
Change requests are not mandatory for major edits, they are recommended when not being sure with the changes on a page.
Deprecated sections have been removed/ update to follow the current strategy.
The documentation guide has been split from one single page into more, small-topic focused pages and a navigation panel has been added to ensure a better flow.
