Re: Ok feedback needed

["John Stowers" <john stowers gmail com>]

On Thu, Feb 21, 2008 at 5:21 AM, Brent Gueth <creeva gmail com> wrote:
>  I know that being programmers documentation is something most of you
>  do not like to do, that's fine I understand that.   What I do need to
>  know is how the current documentation for conduit is looking?
>
>  http://live.gnome.org/Conduit/Documentation
>
>  What I need is what you would look for in a help file or a manual on
>  basic conduit operations (for an end user)  that is helpful, useful,
>  and informative.

I have some documents written on "Conduit and Photos" which give some
nice examples, I will post them to the Wiki ASAP.

>
>  I know at least some of you on the list maybe the type of person that
>  says "Give me the source and I'll figure it out or fix it" for any
>  application you use, but what about your significant other or in laws?
>   What would they need to know to get an understanding without getting
>  mired up in quirks and nuances that you as a developer know?  I know
>  some of these quirks will be sorted out in the long term and as they
>  do the documentation will change.
>
>  After I/we manage to get this documentation in order I can help and do
>  developer manuals to give people that won't a much more technical
>  level an overview of how to dig through things and functions in the
>  code and expectations going forward.

You mentioned in another email that you are currently learning python.
It would be good to hear your opinion on the developer docs on the
Conduit website. Personally I think they are pretty good now, but I am
biased!

>
>  I'll stop acting like a hen mother here and leave my thoughts at that,
>  I would like feedback and thoughts and what has been accomplished and
>  what needs to be.   John has been getting spammed to high heaven from
>  all the wiki edits I have been making.  I think I'm making the one man
>  effort to fill up his gmail inbox (if gmail didn't group messages I
>  would bet he would be really annoyed).

Il give the messages a few hours to slow down, then I will take a look
over the page again, clean up any spelling, english, etc.

>
>  Now for a couple technical questions so you can at least be amused at
>  my lack of knowledge in this realm.
>
>  1.  Anyone have any documentation or links on compiling data into a
>  help file that could be used with conduit (I'm assuming there is a
>  gnome standardized format I hope).

GNOME currently uses a rather arcane XML based documentation format
called Docbook. It is a standard, but it is a bit quirky. Documents
for how to write docbook can be found at

http://library.gnome.org/devel/gdp-handbook/stable/

The reason I chose to start this on the wiki is because it supports
DocBook output

http://live.gnome.org/Conduit/Documentation?action=show&mimetype=text/docbook

This will take some tidying up in order to support all of the extra
formatting used in GNOME docbook manuals, but it should be a usable
start.

Im pretty busy at university this week, so I will not get a chance to
see how easily the conversion to wiki->docbook->gnome docbook will go,
but if you havent got very far by sunday, I might have a try

Any questions, just ask

John

>
>  2.  Anyone know the wiki code for centering?
>  _______________________________________________
>  Conduit-list mailing list
>  Conduit-list gnome org
>  http://mail.gnome.org/mailman/listinfo/conduit-list
>