Whant them to RTFM? WTFM !
Hi guys, once again it’s been quite a long time but don’t worry we are still working hard on Intent.
I’ll try to make a more complete post for the official Intent 0.8 release in a few weeks (integrated to the Kepler release train), but I just wanted to give you a sneak peek of what will be in Intent 0.8.
Intent 0.8: main new features
First of all, as you can see in the Intent 0.8 Release Review Document we got busy this year. We tried to adress in priority the features and bugs raised by the community (through bugzilla or during EclipseCons), for example:
We simplified the syntax of the formal links, which was juged too complex by some users. To link a piece of documentation with a piece of java code, you now just have to write @ref <JAVA_ELEMENT_PATH> (e.g. @ref “com.my.project/src/MyJavaClass.java”). The old (and more complete) syntax is still available, for those who liked to go further and be able to specify things directly inside documentation. We improved the Intent/Java bridge : by simply droping a java class/method/field inside an Intent document, it is automatically linked to the right doc part. To provide a good end-user experience when synchronizing doc & java code, we also added extensible hyperlink mechanisms, image rendering, quick-fixes… We wrote a basic “Getting Started” documentation & cheat sheet, that will be improved soon (feedbacks are more than welcome). In order to improve the end-user experience for writing pure documentation, we added new completion entries, improved the rendering, added a real-time HTML Boostrap Preview of the Intent document…
So please, if you have feedback (positive or negative) or ideas for Intent, do not hesitate to spam us on the Intent forum or on the bugzilla, we will take time to answer.
Intent 0.8: ok but what can I do with it?
Just for those who might not know what Intent is about, the purpose of Intent is to provide tooling for keeping you documentation synchronized with the changes you make on your code (Java/C++ files, Manifest/plugin.xml files, models…). Whenever you modify your code, Intent is able to detect the litlle doc parts that need to be updated, avoiding you a painfull and manual search through whole your doc… You could see Intent as an Agile documentation, able to quikcly react to changes. You may want to read this Jaxenter interview about Intent.
Let’s say you have a document specifying a functional Scenario (Behavior Driven Testing approach), and an acceptance test playing this scenario. You can drop the test method to link it with the doc :
Now that doc & java method are linked, you are able to:
Use hyperlinks to navigate from doc to code Make semantic searches on your doc to easily retrieve all the doc parts related to a java class/method/field through the quick outline (ctrl + O) Keep the two synchronized: any time you will modify this test method, Intent will raise a synchronization issue (visible from problem views). You can visualize it graphically through a compare editor, to determine how you should update your documentation.Everything you need to know about Intent at EclipseCon France
I’m not giving to much details here as I will make a complete presentation of Intent features & extensibility at EclipseCon France.
Attend to the Intent talk and discover:
How to create a good Intent documentation from scratch How to use Intent tooling to keep doc in sync. with the changes you make on your java code How to customize Intent by plugging custom validation rule (e.g. “Any string displayed to the end-user should be externalized”, “Any Acceptance Test should be named after the functional scenario it covers”…) Plenty of other cool stuff, like real-time collaboration around docI’ll be happy if after this talk you are conviced that if you want your team members & users to RTFM, you must start by making a better FM!
Once again, please do not hesitate to spam me with questions if you see me at EclipseCon, I’ll be more than happy to answer, even if I seem to be working, I never do :)
Stay in touch for other Intent news!