Re: [anjuta-devel] Anjuta mallard documentation

[Sébastien Granjoux <seb sfo free fr>]

Hi Johannes,


Le 04/07/2011 10:50, Johannes Schmid a écrit :
> > 1. These information looks quite obvious to me. Do you think it's really needed?

> 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.

I have looked at other documentation, empathy one by example, it really 
tell you which button should be used. It's possible that someone doesn't 
find the context menu himself.


> > 2. there is less explanations about the generate/configure step,
> 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.

Ok.

> There are certain things like custom environment variables that aren't
> that obvious.

What do you call custom environment variable? It has been requested but 
it's not possible to set them for build tools except by writing a plugin.



> > 3. I put the description of each dialog on one page and I have created a
> > index for them. 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.

I have looked at empathy documentation, and if you look for details you 
arrive to a page which explain each setting like: account-irc.page or 
account-jabber.page. It doesn't explicitly described a dialog but it's 
quite close. I'm not sure that "What can I do if anjuta doesn't 
recognize the compiler messages" is really better because you can add 
"What can I do if I cannot find more information about a message on 
internet" and perhaps other uses that I have missed.

Then, adding "What can I do if anjuta doesn't recognize the compiler 
messages" could be useful in a FAQ but I think a description of each 
setting is useful. Then, if you think it's not needed we can remove the 
index of all dialogs.


> > 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.

Ok, I will let it like this.



> > It would be nice to have a complete Mallard documentation for the next
> > stable release. Is there some volunteers?
> I hope I can find some time to add these topics but not sure how far I
> will get.

I hope you won't be the only one to help on that. Should we switch to 
the Mallard documentation anyway for the next release or stay on the 
current one if there is no improvement?


Regards,

Sébastien