Re: [anjuta-devel] Anjuta mallard documentation

["Johannes Schmid" <jhs jsschmid de>]

Hi Sébastien!

> I have just committed the documentation for the build plugin in mallard
> format. I will be interested to have some feedback about it.

First, thanks a lot for taking care of this!

> 1. The text for Compile files, Build targets, Clean targets and Install
> targets is very similar and these information looks quite obvious to me.
> Do you think it's really needed? I have started to put compile, build
> and clean on the same page but I finds it too long.

Yes, it's quite long. IMHO we could shorten this by just explaining what
"Build", "Build Project", "Compile" and "Clean means. It is quite obvious
to find those in the menu (or at the other places). But on the other hand,
it cannot really hurt to have a longer explanation.

> 2. Comparing to the previous documentation (the current in docbook
> format), there is less explanations about the generate/configure step,
> make dependencies. I have looked at other Mallard documentation and it
> looks simpler too, but do you think it's enough?

For my experience this is the step that people have most problems with so
we should probably add some more explanation about the configure step.
There are certain things like custom environment variables that aren't
that obvious.

> 3. I put the description of each dialog on one page and I have created a
> index for them. I have in mind to add a help button on these dialogs
> displaying this help page. Do you think it's useful?

Hmm, in general the documentation team wants to go away from explaining
stuff in the sense of dialogs. So I think it would be better to have
points like "What can I do if anjuta doesn't recognize the compiler
messages" instead of "Configure the build plugin -> Disable translations".
At least this is how I understand that modern help should work.

> 4. I think, we could have one page for each plugin too. I have done it
> but I haven't added an index for all plugins yet.

This is only useful for the non-essential plugins as the user wouldn't
recognize the others as plugins anyway, they should feel part of the core
program.

> 5. I don't know how to link the preference dialog page and the different
> actions (compile, build, install...). I have put the preference page in
> the See Also section and it is referenced in a note in the install
> commmand because I think the use of su and sudo will be quite common.

I can have a look at this.

> It would be nice to have a complete Mallard documentation for the next
> stable release. I can take care of the debugger part then comparing to
> the previous documentation we need only something about editor, code
> navigation and glade plugin. Is there some volunteers?

I hope I can find some time to add these topics but not sure how far I
will get.

Regards,
Johannes