For developers, what about using a tool like Doxygen to document by pulling comments out of the source into a html page. That way they can stay current with the code will minimal effort?
http://www.stack.nl/~dimitri/doxygen/ Dan On Thu, 17 Feb 2005 08:35:35 -0800, Nav Jagpal <[EMAIL PROTECTED]> wrote: > I think a myth-docs mailing list is a great idea. > > How do I go about requesting such a list? > > Thanks in advance > > > On Wed, 16 Feb 2005 17:41:57 -0700, Blammo <[EMAIL PROTECTED]> wrote: > > On Wed, 16 Feb 2005 14:50:08 -0800, Nav Jagpal <[EMAIL PROTECTED]> wrote: > > > MythTV has been getting more and more popular. Now when I mention the > > > software to someone, they actually know what I'm talking about pretty > > > much right away. > > > > > > That is why I think a step-by-step document for installing, and > > > perhaps even using, MythTV would be a good to get a larger user > > > community. > > > > > > I know that a lot of us out there have our favourite distros, hardware > > > encoders etc.. And the combinations of different types of hardware is > > > massive - but what about a document for those non-Linux type people? > > > > > > Document that outlines: hardware (video card, encoder card, sound > > > card, distro) setup. ? > > > > > > For example, I use Debian, and to avoid the whole TV-out hassle, I > > > just used the onboard video card and a VGA->PC converter from KWorld > > > (<$100 CDN). > > > > > > When I went to create my Mythtv box, I had to rumble around the Net > > > looking for various sources.. I wish I could have found a document > > > that said "Hey.. if you get this sound card, video card, etc.. , which > > > will cost you $$ dollars, you can build this box.. And if you have a > > > sound card and video card that *just works*, you'll be set too". > > > > > > Comments/suggestions? > > > > > > > > > On Mon, 7 Feb 2005 18:41:32 -0800, Nav Jagpal <[EMAIL PROTECTED]> wrote: > > > > Thanks for all of the documentation related advice. > > > > > > > > In the next few days I will try to go through existing documentation, > > > > take a look at the users mailing list, and take a look at the source > > > > code (can someone suggest a starting place for the source?... probably > > > > a better for my understanding if I struggle with it anyhow) > > > > > > > > Before I sit down and start writing any documentation, I'll send a > > > > quick outline of what I will be attempting to do, so that I can get > > > > some more advice/comments/suggests before starting. > > > > > > > > Just wanted to send a note so that the people that have already > > > > responded know that I didn't send an email and run away. > > > > > > > > Thanks again > > > > -- > > > > Nav > > > > > > > > > > > > On Mon, 7 Feb 2005 16:13:22 -0800, Brad Templeton > > > > <[EMAIL PROTECTED]> wrote: > > > > > On Mon, Feb 07, 2005 at 09:24:57AM -0500, Daniel Thor Kristjansson > > > > > wrote: > > > > > > On Sun, 6 Feb 2005, Nav Jagpal wrote: > > > > > > ]Is there a need for any type of documentation, manuals, etc? > > > > > > > > > > > > There is a need for developer documentation. Starting with a guide > > > > > > to > > > > > > theming and a guide to producing a debug build and a backtrace for > > > > > > bug > > > > > > reporting. But we also need an overview of the classes and how they > > > > > > interact and something like doxygen for the code itself. > > > > > > > > > > When I started looking at the code I would have loved to have seen > > > > > docs on the scheduler, on the frontend protocol. Also, significant > > > > > sections of the code are uncommented beyond having descriptive symbol > > > > > names -- so adding comments to variable names and function names would > > > > > be an important part of documenting the classes. > > > > > > > > > > As for user docs, one start is reading mythtv-users mailing list and > > > > > seeing what things people are asking the most questions about. In > > > > > some > > > > > cases it is undocumented stuff, in other cases it is documented but > > > > > they are not finding the documentation. In the latter case, it's > > > > > a challenge to reorganize those docs so that even an idiot can find > > > > > the > > > > > answer to their question. > > > > > > > > > > There are also many levels of users, and as Mythtv grows in > > > > > popularity, > > > > > you will see more users who need to be walked through things, folks > > > > > who > > > > > are less linux-familiar etc. > > > > > > > > > > > > > > > > > > _______________________________________________ > > > mythtv-dev mailing list > > > [email protected] > > > http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev > > > > > > > > > > Might not be a bad idea to have a myth-docs email list. That would > > facilitate coop development of docs, give you somewhere to post drafts > > for review and testing, etc. Some of us get paid to proof other > > peoples work, but are terrible at creating our own from scratch. > > > > > > _______________________________________________ > > mythtv-dev mailing list > > [email protected] > > http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev > > > > > > > > > _______________________________________________ > mythtv-dev mailing list > [email protected] > http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev > > >
_______________________________________________ mythtv-dev mailing list [email protected] http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
