Community Call Topic: Collaborative Theia IDE Documentation

[planger]

Hey everyone,

Based on client feedback, I'd like to bring up something I believe could benefit both Theia IDE platform adopters and developers using the Theia IDE.

When crafting a custom product based on the Theia IDE platform, the need for an end user documentation often arises. This documentation usually needs to cover a lot of the shared, generic functionality of the Theia platform that many other custom products also use.

What if we joined forces to create a shared, open-source documentation repository across multiple adopters of the Theia platform? This repository could focus on the generic Theia functionality that's common across various custom products. This approach could save us all a lot of time and effort and help ensure our documentation is both consistent and high quality.

Furthermore, with the new direction of the Theia IDE initiative, which now targets end users directly, there's a clear need for comprehensive user documentation of the Theia IDE itself. This shared documentation repository could serve as a solid foundation for both the Theia IDE and the generic functionalities reused by custom products.

I suggest we explore the idea of starting this shared documentation repository in our next Theia community call. I'm imagining a collection of markdown files, each dedicated to a specific feature or view, organized in a way that makes it easy to generate end-user documentation using existing software documentation tools (e.g. mkdocs, etc.). This could not only benefit Theia IDE end users but also make the documentation process much smoother for custom Theia-based products.

I'm looking forward to discussing this further and hearing what you all think about this idea!

Best wishes,

Philip

@JonasHelming

[hannescmarits]

Hi,
I like the idea to have a user documentation of the Theia IDE "tools" like the Explorer, the Debug view, ...
It would help a lot to get more info about the functionality of the tools, the IDE.
And would help to provide an documentation which corresponds with the current state of the software.
Thanks
Hannes

[JonasHelming]

Great topic, I added it to the agenda!

[sdirix]

The VS Code documentation lives here with the code licensed under MIT and the content under CC 3.0 US. We could evaluate whether it's suitable as a basis for

• developing the customizable documentation framework
• providing the initial Theia IDE documentation

[loneum]

Bear with me if the following sounds too weird or too obvious. I don't know much of this project here yet.

After taking a quick look at (some of) the MD pages of the VSC documentation, I think your suggestion is really worth trying.

I'd just like to point out one thing: I guess that several or many of the existing files are not fine-grained enough in their current form. Maybe we can break them down into individual chunks, which are as independent as possible (i.e., “apply the paradigm of topic-based documentation”, if you prefer it highbrowed 😉). Still, they could be collected and available as larger packages, I suppose, one per content context ("chapter"; e.g., docs/editor, but with even more though smaller files below).
Anyway, it should be ensured that each product can pick its own subset, ideally without having to rewrite anything.

Similarly, to provide a vendor-agnostic template, which ideally everyone can just use without further tinkering, it might help to create a defined set of variables, topic types (looking at you, DITA), a folder structure definition, and the like beforehand.
In case of the previously mentioned MkDocs (personally, I'd go for Material for MkDocs, BTW), one could simply replace every occurrence of VS Code with {{product_name}} and then define variables in the mkdocs.yml, and so on.

[hannescmarits]

This would need some kind of change management.
Some for the case the behavior of VSC has been changed, and this influences part of Theia, and therefore the documentation.
But something for this must already exist for the Plugin API, ...
And some for the case the VSC behavior and documentation is adapted, but it the functionality differs from Theia, i.e. the DEBUG view, or the EXPLORER.

Just two examples:
VSC Folders, Theia Explorer

VSC Debuger vs Theia Debug