Home » Archived » Mylyn Intent » How to introduce Intent in development process
|
| Re: How to introduce Intent in development process [message #1048526 is a reply to message #1048295] |
Wed, 24 April 2013 15:43   |
|
Hi Davide,
thanks a lot for your interest in Intent!
First of all, let me be clear with you: Intent is still in incubation
phase, and although I'm conviced that its feature are exactly tackling
the main issues that we have with documentation, some problems (mainly
performances but also some missing features) still remain in this 0.8
Kepler version.
My first (and a bit hypocrite) answer would be to say: "well the impact
with current development activies is null: you use an Intent doc as any
doc, the only difference is that when you are writing a piece of doc you
drag and drop the Java class/method, model... it is explaining)."
You can test it by yourself:
- downlad a Kepler M6
- install the Mylyn Intent 0.8 nightly
http://download.eclipse.org/intent/updates/nightly/0.8 (which provides
bugfixes and new features like an improved syntax highlighting and a
brand new 'Preview view' which provides live HTML Bootstrap preview of
your documentation).
- Use the Intent new project wizard to create an Intent doc and use the
provided templates to initialize it with a content.
- notice that you can open an Intent editor on any sub-part of the
documentation, no matter how small (a chapter, section,
subsubsection...), to only have above the eyes the piece of doc that is
relevant to your current task, and not a hudge document
- Inside a section, drop a java method:
==> The link is automatically created and displayed with an image (of
course you can override this renderring according to what you are dropping)
==> you can use hyperlinks (ctrl+click) to open the java method from the doc
==> you can use ctrl+o (quick-outline) to easily retrieve all the doc
parts related to this java method (default scope of the search is the
current editor, but if you type ctrl+o again you will browse through the
entire documentation)
==> if you modify the java class, you will get a synchronization issue
(displayed in the problem view) that you can visualise using the "See in
compare editor" quick-fix
==> update the textual documentation to reflect the changes you made on
your java method, and then use the "Mark documentation as merged"
quickfix to say to Intent that you have updated your doc.
==> Use the "export documentation as HTML" action from your Intent
project to export the doc into HTML (other export formats like Latex &
PDF will come soon, hopefully for Kepler)
So as you can see, the process changes are not too heavy: developpers
will write their documentation as usal, but in addition they just have
to think about associating their doc parts with the corresponding
artifacts by dropping them at the proper location.
In regards to "the right way to sell it", well as a developer, when I
modify my models or my java code and want to document this change, I
have to spend so much time browsing manually through the hundred of
pages of my software doc just to find out the related doc parts (without
being sure that I found all of them). If you are using Intent, this
painful job is made for you, so you gain in productivity and can focus
on writing meaningful doc.
Moreover, the benefits are not only for the doc writers but also for the
readers: as an outdated documentation is worse than no doc at all,
readers often mistrust and hence don't read design & technical docs.
My second (and more honest) answer is that I'm perfectly aware that most
developers are not used to write a good documentation, and we have to
promote a formal approach for guiding them and helping them writing doc.
I've just started working with Obeo guys who are trying to define a
process for using Intent to specify the UMLDesigner modeler (available
on the Eclipse Marketplace). You can find their Intent documentation
here https://github.com/ObeoNetwork/UML-Modeling/tree/master/documents ,
be aware that this is clearly a prototype to provide a good methodology
for writing useful doc. I'm ready to answer any question you may have
about it.
One last thing: as you may have noticed, documentation about Intent is
almost inexistent, and you could say it is outrageous for a
documentation tooling. Well, you're right, but I'm doing this on purpose
: once I will have every tools I need to document Intent (and I'm almost
here), I'll try to retro-document the whole software using Intent. This
is a perfect use-case : if Intent allows me to easily retro-document
Intent, then it is proof that the software is mature enough to be
applied on hudge software.
Please do not hesitate to post again if you have more concrete question
or feedbacks, I'll be glad to answer.
Of course, anyone with usecases and feedbacks is welcome to answer
David's question, and file new bugzillas with bugs & feature requests
https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Mylyn%20Docs%20Intent :)
Best regards,
Alex
Le 24/04/2013 14:49, Davide Dalle Carbonare a écrit :
> Hi all,
> I'm planning to introduce Intent in the development process, and I'd
> like to know from who of you that already done this, your experience,
> suggestions and difficulties.
> My main concern is that I want to lower as much as possible the impact
> with the current development activities and at the same time I have to
> find the right way to sell it to the team by proving the benefits they
> may gain.
>
> Thank you in advance for any tip you may have.
> BR
> Davide
|
|
| |
| Re: How to introduce Intent in development process [message #1053229 is a reply to message #1053215] |
Fri, 03 May 2013 09:16 |
|
Hi Davide,
even if I want to use Intent to document Intent in the long run, I will
write a simple Getting Started Guide in Textile for the Kepler release.
You can get a sneak peek of this getting started guide on Intent wiki
http://wiki.eclipse.org/Intent/Getting_Started#First_example_:_synchronize_Java_code_with_Intent
Thanks again for trying Intent !
Best regards,
Alex
Le 03/05/2013 09:40, Davide Dalle Carbonare a écrit :
> Wow! Alex, thank you very much for your answer.
>
> You've clarified me some points that were still obscure to me ...
>
> I've understand the project status and I'll proceed with a restricted
> test drive that involve a small project. This project exposes a set of
> RESTful services and the plan may be to document these APIs using Intent.
>
> I'll look at the prototype done for Obeo as soon as possible and as soon
> as I can start my experimentation I'll send you some feedback.
>
> Cheers,
> Davide
>
> ps: I support your plan for creating Intent documentation.
>
|
|
|
Goto Forum:
Current Time: Tue Apr 23 07:17:18 GMT 2024
Powered by FUDForum. Page generated in 0.03266 seconds |
] 
Search
Help
Register
Login
Home
