Here are some doc-related practices/organizational aspects I’d like that we discuss/agree on (discussed today in an online meeting with some of you):
A) The doc page for each extension must clear materialize 3 sections:
one for the user aspects of the extensions
one for the admin aspects of the extensions
one for the dev aspects of the extensions
Goal: So that the different categories of users can clearly focus on the sections they’re interested in.
I’d even propose that even if a section doesn’t exist (like an extension not having any admin aspect, or an extension not offering any API and thus no developer content), it should be mentioned explicitly that this extension doesn’t provide it.
B) Update the Repository app used on e.x.o (either something specific to e.x.o or generic in the app) to:
Display the 3 sections mentioned in point A)
In edit mode, have 3 text areas, one for each section
Goal: To ensure we follow the best practice defined in A)
C) Agree that there are 2 kinds of docs that should remain in the platform wiki and not be moved to the extensions wiki:
Tutorials that span several features
Generic concepts should also remain in the general doc, with pointers to exo, e.g.
D) Since the Features page lists features that have user, admin and dev aspects, move it directly under the Documentation space, possibly using a custom LiveTable/LiveData.
E) Continue moving the doc for features that are in oldcore, by importing the oldcore extension on e.x.o and naming it “Core” there (oldcore would be a bad name for our readers ;))
F) Check and improve search on xwiki.org so that only doc content is returned (and not XS or app pages installed on the various wikis), to improve the relevancy of the returned results.
Once/if agreed, I’ll then update our doc guide, for points A), B), C).
Totally agree. I think it would make it easier for every type of reader as they could just skip to the section they’re interested in.
Agreed, it would help ensure consistency. Might I suggest adding a link to the contributing guide, or a document outlining the current best practices inside the editor view?
Seems fair, however the documentation pages moved to exo should still be easily findable from within the documentation.
Either by making the search have higher visibility, or by keeping links inside the docs that bring the users to the exo page.
Sounds good. The page would need to return a redirect tho, as search engines are not that fast at indexing, and may point users to the old, broken link for a couple of days.
I don’t fully understand this technical/historical aspect, but it sounds like the change would clarify some things so I’m on board.
100% agree here. The search on xwiki.org should be good enough that we ourselves can and want to use it.
+1 but, what’s the migration path here? How do we move from one generic field to 3 dedicated ones?
+1
I’m not fully sure of what you want to do here. But, the Documentation page looks large enough as it is, and I’m not sure adding more content here would help.
+0
I’m also fine with letting (old)core documentation directly in xwiki.org
If XS or app pages are shown in the search, that sounds like a bug to me that should be fixed in the affected apps and not just on xwiki.org.
This sounds good in general, however, for many extensions we currently have several pages, usually there is a UI extension on which we document the user-visible features and possibly the admin UI and then there is an -api and/or -default extension on which we document things like configuration files and developer APIs. This isn’t very user-friendly as it is hard to understand the separation into different extensions (which is purely for technical reasons) and it is sometimes hard to find the different parts. Sometimes the documentation is also split between a macro and an application that share the configuration. An example for this is office import: There is the Office Importer Application, but the configuration of the presentation import is only described on the page of the Office Macro, even though it also applies to the office importer application. Did you discuss how to deal with such cases and how to make such documentation easier to discover? Adding these extra sections for user, admin and developer aspects doesn’t really help with this I think. Moving more documentation to extension pages might make this problem even worse as it will further scatter the documentation in ways that are hard to understand by users as the documentation will be grouped by technical modules instead of functionality.
+1. The hard part here is deciding which of the 3 sections the current content is assigned to (I guess the less bad is Users even it’s definitely not going to be accurate for many extensions).
I assume you mean the main wiki here, as the platform wiki does not really exist anymore.