TB Documentation effort
hold...@gmail.com
Thunderbird documentation for the 3.0 release? I know there's some
scattered around the Mozilla Wiki, the Mozillazine Knowledge Base, a
bit of it on developer.mozilla.org, and probably lots more scattered
in extensions and other websites around the world.
Not being involved at all in development, I'm not sure I'm qualified
to comment, but I'm willing to start stuff out. Write interface
documentation. Move Knowledge base articles. Or even write little code
snippet examples. Just not sure where to start (and don't want to
write documentation for things that will change drastically in the
coming months).
Is DevMo even willing to host TB documentation as well as FFs? Seems
like interface documentation/examples/tutorials would fit well within
it if that's OK, and (obviously?) planning docs seems to fit in well
on the wiki.
I think having something started would be good even as interfaces are
rewritten though. TB can start adding doc-needed comments to bugs too,
and making sure that as things move forward we don't make them even
more confusing for extension authors/who ever else decides to use the
code. Better to do that now than later.
Gary Kwong
lot of our documentation (most likely WIP stuff / old archives) are in
the Mozilla Wiki, and not a lot of Thunderbird-specific material are
actually in MDC.
Since MDC already has most of the backend wiki infrastructure set up,
I'm leaning towards having documentation for Thunderbird there.
Thoughts?
-Gary
David Ascher
> David said to start a discussion here. What's the feeling on
> Thunderbird documentation for the 3.0 release? I know there's some
> scattered around the Mozilla Wiki, the Mozillazine Knowledge Base, a
> bit of it on developer.mozilla.org, and probably lots more scattered
> in extensions and other websites around the world.
>
> Not being involved at all in development, I'm not sure I'm qualified
> to comment, but I'm willing to start stuff out. Write interface
> documentation. Move Knowledge base articles. Or even write little code
> snippet examples. Just not sure where to start (and don't want to
> write documentation for things that will change drastically in the
> coming months).
>
I suspect the answer depends on what is meant by documentation, with
different kinds of content needing different kinds of infrastructure,
process, etc.
One of the things that's been missing I think is someone with a holistic
view on what "Thunderbird documentation" is. I know that I at least
keep discovering new bits of content in various places, but it's a big
job to grapple w/ it all at once.
If you're keen to start, I suggest you define something you'd like to
see done, and I'm quite sure you'll find people to help.
> Is DevMo even willing to host TB documentation as well as FFs? Seems
> like interface documentation/examples/tutorials would fit well within
> it if that's OK, and (obviously?) planning docs seems to fit in well
> on the wiki.
>
I'm quite sure that devmo is more than happy to host stuff for Tb, as
they do for Fx.
> I think having something started would be good even as interfaces are
> rewritten though. TB can start adding doc-needed comments to bugs too,
> and making sure that as things move forward we don't make them even
> more confusing for extension authors/who ever else decides to use the
> code. Better to do that now than later.
>
+1
Thanks for stepping up!
--david
Dan Mosedale
>
> I suspect the answer depends on what is meant by documentation, with
> different kinds of content needing different kinds of infrastructure,
> process, etc.
>
> One of the things that's been missing I think is someone with a holistic
> view on what "Thunderbird documentation" is. I know that I at least keep
> discovering new bits of content in various places, but it's a big job to
> grapple w/ it all at once.
I agree that we could certainly use someone thinking about all of this
stuff in a big-picture sense, but that doesn't feel like a particularly
pressing short-term requirement. I suspect that following existing
conventions (e.g. deployment / power-user / support docs on MozillaZine,
extdev docs on developer.mozilla.org, etc.) is likely to take us pretty
far. So I'd suggest pressing forward in that direction...
Dan
Chris Ilias
> Is DevMo even willing to host TB documentation as well as FFs?
The ISP hooks doc is there, so I would say yes. :-)
http://developer.mozilla.org/en/docs/Thunderbird_ISP_hooks
--
Chris Ilias <http://ilias.ca>
List-owner: support-firefox, support-thunderbird, test-multimedia
Sheppy
>
> > Is DevMo even willing to host TB documentation as well as FFs?
Yes, absolutely. We've been assuming that the Thunderbird developer
documentation would go on MDC, since there's so much shared material.
My feeling is that Messaging can for the most part handle their own
documentation on the writing and editing side, while I'll keep an eye
on things to make sure it all works in the context of the site and
perhaps occasionally pitch in some edits if the mood strikes me. :)
Eric Shepherd
Developer Documentation Lead
Mozilla Corporation
http://www.bitstampede.com/
Joshua Cranmer
> David said to start a discussion here. What's the feeling on
> Thunderbird documentation for the 3.0 release? I know there's some
> scattered around the Mozilla Wiki, the Mozillazine Knowledge Base, a
> bit of it on developer.mozilla.org, and probably lots more scattered
> in extensions and other websites around the world.
Doxygen comments on the IDL files are a good place to start with
documentation, and there, frankly speaking, the documentation is
extremely poor. <http://doxygen.db48x.net/mozilla/html/classes.html> is
a starting point (warning: documentation for more than just mailnews
IDLs), although doxygen seems to be missing some critical IDL files. I
also know that there exists a script to convert Doxygen files to
MDC-style files as well, although its location escapes me at the moment.
Personally, I make it a goal that anytime I touch an IDL file, I
document anything new I add, and sometimes I add documentation when I'm
not actually touching the IDL file but the implementation code. I'm sure
other developers hold similar personal commitments.
> Not being involved at all in development, I'm not sure I'm qualified
> to comment, but I'm willing to start stuff out. Write interface
> documentation. Move Knowledge base articles. Or even write little code
> snippet examples. Just not sure where to start (and don't want to
> write documentation for things that will change drastically in the
> coming months).
This summer, I am writing a guide to defining a new account type in
mailnews as part of my work with listarchive. The WIP guide can be found
here: <http://wiki.mozilla.org/MailNews:Creating_New_Account_Types>. I
hope that other people may find the time to write guides for extension
developers for similarly complex aspects of mailnews.
Dan Mosedale
> I also know that there exists a script to convert Doxygen files to
> MDC-style files as well, although its location escapes me at the moment.
At one point in early MDC planning stages, there was a hope of
transcluding the IDL stuff into MDC pages directly, but that ended up
not happening. As far as I can remember, at least part of the reasoning
was that it was going to be too hard to keep them in sync. Sheppy, does
DekiWiki offer any hope on that front?
> Personally, I make it a goal that anytime I touch an IDL file, I
> document anything new I add, and sometimes I add documentation when I'm
> not actually touching the IDL file but the implementation code. I'm sure
> other developers hold similar personal commitments.
Indeed, when I review code where someone touches an IDL file, I
generally request that they add doxygen comments for the
methods/attributes that they touched, at the very least. I'd encourage
all reviewers to do this.
Dan
Axel Hecht
> Joshua Cranmer wrote:
>> I also know that there exists a script to convert Doxygen files to
>> MDC-style files as well, although its location escapes me at the moment.
>
> At one point in early MDC planning stages, there was a hope of
> transcluding the IDL stuff into MDC pages directly, but that ended up
> not happening. As far as I can remember, at least part of the reasoning
> was that it was going to be too hard to keep them in sync. Sheppy, does
> DekiWiki offer any hope on that front?
>
I think the biggest issue here is that once you start to autogenerate
those, you can't really edit them in the wiki anymore.
The actual conversion/updating thing shouldn't be too hard, I guess.
Axel
Dan Mosedale
>
>> At one point in early MDC planning stages, there was a hope of
>> transcluding the IDL stuff into MDC pages directly, but that ended up
>> not happening. As far as I can remember, at least part of the
>> reasoning was that it was going to be too hard to keep them in sync.
>> Sheppy, does DekiWiki offer any hope on that front?
>>
>
> I think the biggest issue here is that once you start to autogenerate
> those, you can't really edit them in the wiki anymore.
Over the years, I've heard of various UI that allows for annotation of
documents. Seems like that could apply here, though I'm unclear how
practically and how easy to use it would be .
Dan
Ron K.
The Mail Tweaks extension by Rod Whitley has a Pen Annotation option.
Available at mozdev.org.
--
Ron K.
Who is General Failure, and why is he searching my HDD?
Kernel Restore reported Major Error used BSOD to msg the enemy!
Mark Banner
I think something that would help us is a rough outline as to what
should go where. For instance extdev docs - what do/should they consist
of? Is devmo only about extdev, not as far as I can tell.
Not only that is where should things go on devmo? If I go to the devmo
main page I see nothing related to mailnews
interfaces/thunderbird/seamonkey. Whilst I found
http://developer.mozilla.org/en/docs/Extensions:Thunderbird within a
couple of clicks, is there other documentation we should be putting on
there other than how to use interfaces?
I'm not looking for a full list now just some guidelines to help folks
get started.
I think balancing the documetation between wmo and devmo is something we
also need to be careful about, the bit below has some examples of where
I think we've got the balance wrong/right etc. Apologies for the length,
I thought it might be worth exploring some examples.
Standard8
Taking a quick look in http://wiki.mozilla.org/Category:Thunderbird and
some of the surrounding Thunderbird/Mailnews pages, I see:
http://wiki.mozilla.org/Thunderbird:Build
This has build instructions for Thunderbird and Build Machines -
historically, the build instructions for Mozilla apps have been on
devmo. If the devmo instructions aren't good enough, then we should be
extending those rather than adding our own.
Most of that "build" information is actually regarding debugging and
should probably be moved to a related section/page.
We've also got the Build Machines section on that page. Maybe that would
be better on a "Thunderbird:IT:Build_Machines" page, i.e. in a separate
section for IT.
I'm not saying we shouldn't have a Build page, but, maybe it needs
balancing more to not duplicate/extend existing documentation but to
make it easy for users finding the Thunderbird wiki pages to find the
main sources of information.
To contrast the build page, here is one that I think is reasonably well
balanced:
http://wiki.mozilla.org/Thunderbird:Debugging
It provides pointers to the relevant information, and doesn't attempt to
duplicate what we already have.
Things like:
http://wiki.mozilla.org/MailNews:Automated_Testing
http://wiki.mozilla.org/MailNews:Performance_Testing
http://wiki.mozilla.org/Thunderbird:Code_Layout
I think are in a grey area between devmo and wmo.
Something like
http://wiki.mozilla.org/User:Emre/tb/architecture/diagrams probably
needs to be moved to devmo at some stage when its a bit more mature.
Joshua Cranmer
> I think something that would help us is a rough outline as to what
> should go where. For instance extdev docs - what do/should they consist
> of? Is devmo only about extdev, not as far as I can tell.
To me, articles on devmo feel like they should be complete, so WIP
guides should probably be hosted on wmo until they are completed. IMHO,
though, I think that broad extension development guides (like creating a
custom column) should ultimately make their way to devmo, along with
some objects like interface documentation. Guides that are more internal
(like the mailnews related standards page) should probably stay in
wmo, but this is a very gray area.
> ... Apologies for the length, ...
I'd consider a long post to be in the region of 500 or more lines, so no
need to apologize.
> Things like:
> http://wiki.mozilla.org/MailNews:Automated_Testing
> http://wiki.mozilla.org/MailNews:Performance_Testing
> http://wiki.mozilla.org/Thunderbird:Code_Layout
>
> I think are in a grey area between devmo and wmo.
The testing information feels more right, to me, to be on wmo, but based
on other documentation, it seems like the testing stuff should make its
way to devmo.
> Something like
> http://wiki.mozilla.org/User:Emre/tb/architecture/diagrams probably
> needs to be moved to devmo at some stage when its a bit more mature.
+1
Dan Mosedale
> To me, articles on devmo feel like they should be complete, so WIP
> guides should probably be hosted on wmo until they are completed. IMHO,
> though, I think that broad extension development guides (like creating a
> custom column) should ultimately make their way to devmo, along with
> some objects like interface documentation. Guides that are more internal
> (like the mailnews related standards page) should probably stay in wmo,
> but this is a very gray area.
From what I've seen, completeness is not a criterion for stuff to be on
devmo. But what the exact criteria is feels gray to me as well. It
seems like it might be some combination of "likely to be useful to folks
outside of or just entering into the core mozilla community" and
"maintained-ness". Really, though, I'd be especially interested in
hearing Sheppy's thoughts here; for all I know, this is written down
somewhere.
Dan
hold...@gmail.com
exists) over to MDC lately (the hard way apparently as I've never seen
the doxygen converter before (http://starkravingfinkle.org/projects/
mdc/doxygen-to-mdc.html). I also made a main "Thunderbird" page, which
others can edit if they feel the need to. There are sorta two
Categories in effect: Thunderbird and MailNews which probably should
either just be combined or separated better. And some new build info
for comm-central went up, which is nice.
Like was mentioned, most of the interface needs a lot of work
(documenting functions and parameters and whatnot) and what I have
written needs some looks over by people in the know to make sure its
somewhat correct. Regardless, I figured its a start. I'm trying to
stay away from things that I know have/had changes in store until I
hear that they're settled. And it can be back ported into the source
once its written up in some way if people want that.
Quick request for anyone with power of review or who writes code
though. Can we at least start marking bugs with dev-doc-needed or tb-
doc-needed or something to make searches easier. I'd gladly go through
a bunch later and incorporate changes, or even write little tutorials
which can be cleaned up by someone with more knowledge if there's need
be. Its just hard to find the info without watching checkins
religiously. Even if there's an easy converter for doing the initial
switch, it seems better/easier to just go in and document changes by
hand (along with some notes about when/where/why things changed).
Stefan Hinz
> Well I started moving interface documentation (or what little of it
> exists) over to MDC lately
Can you tell me where the interface docs can be found? I'd like to help
reviewing.
Thanks,
-Stefan
> _______________________________________________
> dev-apps-thunderbird mailing list
> dev-apps-t...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-apps-thunderbird
Regards,
Stefan
--
***********************************************************************
Sun Microsystems GmbH Stefan Hinz
Sonnenallee 1 Manager Documentation, Database Group
85551 Kirchheim-Heimstetten Phone: +49-30-82702940
Germany Fax: +49-30-82702941
http://www.sun.de mailto: stefa...@sun.com
Amtsgericht Muenchen: HRB161028
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Vorsitzender des Aufsichtsrates: Martin Haering
***********************************************************************