Hi all, and Happy new year! :)
A little bit off-topic: should we split documents in different files? For example:
454275: [Profiles] Documentation shall be reworked
https://bugs.eclipse.org/bugs/show_bug.cgi?id=454275
Having multiple files for a documentation topic most likely improves maintainability and file-diff, but the side effect is on the user: when reading the document,
the navigation is tedious, because we need to go back & forth after each section. It doesn’t seem to be possible to have the complete document on a single page if it is split in multiple files, and there is no link to jump directly to the next section. I guess
it is possible to manually add these links, but then the documentation wouldn’t really be maintainable anymore. If anyone knows of a mechanism to automate or improve 00this, then splitting documents is probably relevant; but otherwise, I feel that adding a
TOC at the top of the complete document (in a single file) is much more efficient for navigating.
And I notice that some documents don’t include the TOC at all, so a quick reminder for everyone: add __TOC__ at the beginning of the *.mediawiki file before
generating the Eclipse Help, and everything’s magic :)
Regards,
Camille
De : mdt-papyrus.dev-bounces@xxxxxxxxxxx [mailto:mdt-papyrus.dev-bounces@xxxxxxxxxxx]
De la part de MAGGI Benoit
Envoyé : lundi 5 janvier 2015 10:16
À : Papyrus Project list
Objet : [PROVENANCE INTERNET] Re: [mdt-papyrus.dev] [PROVENANCE INTERNET] Re:[PROVENANCEINTERNET] Re: [PROVENANCE INTERNET] Re:Documentation forplugin in plugin
Hi Christian,
I think that the structure of the repository should be design to help developers/committers :
ð
As Onder said : it’s easier for a newcomer (even for experienced developer) to find and keep up to date documentation if it’s on the same place as
the code.
About help.eclipse.org, we should write a little mojo for tycho and have a specific packaging grouping all documentation in one plugin
(I believe it’s what is required by the admins :
“the
name of your help plugin and where we can find it on download.eclipse.org”)
ð
As François said : packaging goal shouldn’t have any impacts on our plugin/directory structure
Happy New Year,
Benoit
Hi,
One good reason for packaging documentation separately from all of the other plug-ins is so that it can be deployed separately, for example in the Eclipse Infocenter: see bug 443315 [1].
Papyrus wasn’t contributed to help.eclipse.org in Luna; it must be in Mars. And should be for Luna SR2 also, IMO.
But I think that documentation about main plugin must be inside. In this maner maintenance can be facilitate the second reason from Benoit.
For example I have found document about sash editor done by cedric dumoulin in the directory doc. (this doc was done with the version before papyrus eclipse).
I think that It was not maintained because everyone have forgotten that a doc existed somewhere..
To my mind, it is important/critic to be able to separate each element/plugin.
A plugin should come with its own documentation, source code etc… It could live alone.
So I join Benoit’s proposition.
If you want to have doc packaged for all items/plugins, even if the plugin itself is not packaged inside the Papyrus RCP, then you have just to write a different
releng for your papyrus rcp that aggregates all documentation from all registered plugins.
I do prefer this approach.
+1. Extra plgins should also précise that they have to be added to Papyrus first to be used.
Extra-plugins can come with an installation guide, so it also makes sense to have the Documentation plug-in without having the plug-in
That was the case for example for the CSS Plug-in when it was still an extra-component, and it’s the case for CDO as well
It also gives more visibility to components when they are not installed
All documentation plugins are (or at least should )stored here : org.eclipse.papyrus\plugins\doc\*.doc
My question is : Why don’t we keep the documentation in the plugin it describes ?
For example : org.eclipse.papyrus.infra.gmfdiag.common.doc should be included in org.eclipse.papyrus.infra.gmfdiag.common
- Easier
for a newcomer to find documentation when trying to add a feature
- Easier
to think of updating the doc when its already in the workspace
- Easier
to follow impact on documentation (same dependency tree as plugins)
- Won’t
miss documentation in the build when packaging an rcp or updating plugins
The only bad thing I see is that it won’t be any more possible to create a custom rcp without documentation but who will need that ?
_______________________________________________
mdt-papyrus.dev mailing list
mdt-papyrus.dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/mdt-papyrus.dev
