[XWiki Docs Reorg - Batch 15]: Add a “Documentation Resources” Section to the Documentation Guide

[elenicojocariu]

Proposal 21: Add a “Documentation Resources” Section to the Documentation Guide

To improve the visual quality and realism of documentation, this proposal introduces a new section in the documentation guide dedicated to contributors who want to add screenshots or example content. The section suggests a predefined environment, provided as a XAR package to ensure that the examples are realistic, visually appealing, and close to real use cases. The use-case proposed is an Intranet environment.

For example, the environment should include predefined:

• Wikis:

  • Main Wiki: Home
  • Additional Wiki: Projects

• Users with realistic names: John Smith, Ana Smith, Alex Johnson

• Avatars:

  • John Smith, Ana Smith, Alex Johnson:
    
    
    
    
    
    
    
    

• Emails

  • john.smith@example.com, ana.smith@example.com, alex.johnson@example.com

• Spaces:

  • Home Wiki:

├─ Welcome
├─ ├─ Introduction
├─ ├─ About Company 
├─ News
├─ ├─ Announcements
├─ ├─ ├─ Updates
├─ ├─ Events
├─ ├─ ├─ Hackathon

• Projects Wiki:

├─ Project List
├─ ├─ Project 1
├─ ├─ ├─ Overview
├─ ├─ ├─ Strategy
├─ ├─ Project 2
├─ ├─ ├─ Overview
├─ Meeting Notes
├─ ├─ Strategy 1
├─ ├─ Strategy 2
├─ Best Practices

• Text and Attachments: The content on all pages is generic (“Lorem ipsum…”), attachments are organized realistically to make the pages appear like true content. This way, a realistic structure and layout are presented, while keeping the actual text content generic.

The idea is to encourage contributors to provide screenshots and examples using realistic examples, making the documentation more engaging.

WYT? Thanks!

[gabrielc]

Hi Eleni! Thank you for your proposal!!

I think this is a good idea since it would ensure that the screenshots presented inside docs pages would look consistent. So +1 from me.

I do have one suggestion though

@elenicojocariu

The content on all pages is generic (“Lorem ipsum…”)

It may be interesting to generate the content with AI, instead of just using “Lorem Ipsum”. I think it would improve the realism (using AI for realism, ironic I know).

[vmassol]

@gabrielc

It may be interesting to generate the content with AI, instead of just using “Lorem Ipsum”. I think it would improve the realism (using AI for realism, ironic I know).

+1

Resources:

• https://medium.com/yld-blog/lorem-ipsum-is-dead-long-live-the-ai-76d631aee835
• LukeW | The Death of Lorem Ipsum

[elenicojocariu]

The initial idea was to keep the focus on layout, structure, since readers of doc pages are not usually interested in the actual text content shown in example screenshots. But I agree that using AI-generated placeholder text could bring an extra level of realism. I’ll include it.

Thanks!

[mleduc]

+1, thanks

An optional bonus could be to have a xar available (or even an extension) with all those resources easily available.

[elenicojocariu]

Hi! This is already part of the proposal:

@elenicojocariu

The section suggests a predefined environment, provided as a XAR package to ensure that the examples are realistic,

Thanks!

[vmassol]

@elenicojocariu

The section suggests a predefined environment, provided as a XAR package to ensure that the examples are realistic, visually appealing, and close to real use cases.

The reasons are wrong for the XAR… The reason for it is to make it easier for doc writers to use the predefined resources.