I think you should wait for the GUI tools before you begin documenting the API. Miguel and I have had a talk about this last night and I believe we are on the same page now. The tools should be forthcoming. In the meantime please proceed with your plans to add documentation for some of the other tools.
Cheers, Adam On Tuesday 03 September 2002 09:39 am, Willem J.W. Semmelink wrote: > Hi all > I am a new subscriber on the list, so I can just as well tell who I am. > I live in Pretoria, South Africa, and I have some 7 years experience as > a software developer, mostly using a 4GL or C++ for development. I got > interested in .Net from last year, and I visit the Mono website > regularly since an article appeared in DrDobs in January. > > In a recent MONO for Windows installation package, the following text > > appeared in the file Helping.HTM: > >> If you are a programmer you could help the mono project at > > go-mono.org > > >> Of course not as important, but still cool, I think it would be to > > have something like the "Start here" Overview in the .NET Framework. > > >>This would include >>examples, tutorials and Quickstart Guides, a > > better README, an overview about the tools, possibly a C# tutorial. > > >> If you have some good ideas and are better in english than I am you > > could help ;-) > > >> Johannes Roith > >>mail: [EMAIL PROTECTED] <mailto:[EMAIL PROTECTED]> > > After several e-mails to the above address returned undelivered, I then > decided to subscribe to the list, and air my views here. I think I can > perhaps help with an overview of the tools and the C# tutorial. > > An archive of the list focused on an XML format for these external > documents - I am uncertain whether the issue is closed, and whether a > standard format now exists for such documents. The XML examples I saw, > are more relevant to documenting the .NET API than a training manual, > e.g. > <class name="System.Object"> > <method>string ToString ()</method> > <method>int GetHashCode ()</method> > </class> > After reading the list archives, I can also not exactly determine > whether I should still wait till the GUI tool and browser tool are > finished before contributing. If a standard DTD for a training doc is > set, I can start contributing by typing the raw XML. At the bottom of > this <long> message, I propose an outline of a tutorial page. Perhaps we > can design a DTD specifically for that purpose. > A good starting point would perhaps be to determine a table of contents > for a "start here" document. I propose one below. Hope that my > contribution helps. > Greetings > Willem Semmelink > > My suggestion for a table of contents: > 1. What is the mono project? > 1.1. Overview of Microsoft .NET. <standardisation of the common > language, and C#> > 1.2. Overview of MONO. > 1.3. Tools: compiler, runtime, linker, debugger, etc.. > 1.4. Other tools available: SharpDevelop IDE, NAnt, NUnit, ... > 2. Getting started > 1.1 Installing Mono > 1.1.1 Hardware and software requirements > 1.1.2 Installation procedure (separate entries for each > operating system) > 1.1.3 Directory structure of the installed product and > purpose of sub-folders > 1.1.4 List of the installed files and their Purpose > 1.2. Hello World application > 1.2.1. Illustrate use of the compiler command-line > syntax > 1.2.1. Basic C# program structure: class with main > member function, etc... > 1.3. Running a program: use of the mono run-time > 1.4. Microsoft .NET > List the Mono files and their corresponding Microsoft > counterparts. > Describe any differences in usage > 1.5. Working with Gtk# > 1.5.1. Installing Gtk2 on Linux, Windows .... > 1.5.2 Installing Gtk# > 1.5.3 Example program > 1.5.4 Errors and possible causes > 1.5.5 More information (Refer to Gtk manual?) > 1.6. Working with Qt#? > 1.7. Working with Windows.Forms (probably only when Mono classes > were sufficiently implemented ) > 3. C# tutorial > 3.1 Introduction > 3.1.1. Tutorial conventions > 3.1.2. Where to get assistance: published books, > newsgroups, on-line help > 3.2.3 C# introduction (C - C++ - C# ) (C# and Java) > (why use C#)? > 3.2.4 C# Hello World application: main language features > - Application startup > - Application termination > (and mention garbage collector?) > - > 3.2.5 Overview of the C# compiler > 3.2. C# Types > 3.2.1 Static versus dynamic memory management > - Value types versus reference types > - Boxing and unboxing > 3.2.2 Variables > - Categories of variables > - Declarations > - basic types > - enums > - variable assignment > - type conversion (implicit | explicit) > > 3.2.3 Structs > 3.3.3 Classes > - Class declarations > - Constructors > - Destructors > - Class members > = Struct, enum, class, interface, array > etc > = Accessibility: private, protected, > public, internal > = overloading, > - Fields > - Methods > - Properties > - Events (Delegates) > - Indexers > - Operators > 3.3.4 Arrays > 3.3.5 Enums > 3.3.6 Interfaces > 3.3.7 Namespaces > - namespace declarations > - Compilation units > - using directives > 3.3. Program structure > 3.3.1 Expressions > - Defined > - Operators (presedence, overloading, unary, > binary) > - Function calls > 3.3.2 Statements > - Block statements > - Declaration statements > - Selection (if, switch) > - Iteration statements > - foreach and collection classes > - Jump statements (break, goto, continue, > return, throw) > - try, locked, check, using statements > 3.3.3 Line terminators, white space and comments > 3.3.4 Grammar: > Identifiers, Keywords, Literals > 3.5 Strings > 3.4.1 Unicode > 3.4.2 Char > 3.4.3 String > 3.4.4 Escape sequences > 3.4.5 StringBuilder class > 3.6 Exceptions > 3.7 Unsafe code > 3.8 Libraries and platform invokes (perhaps illustrate using > GTK# internals as example) > 3.9 GUI programming using Windows.Forms > 3.10 The C# compiler in detail > 3.10.1. Compiler command-line options > 3.10.2. Compiler errors > 3.11 Preprocessor directives > 3.12 XML documentation > 3.13 Windows COM / Gnome Bonobo interoperability > 3.14 Threading > 3.15 Security > 3.16 Database access > 4. .Net class libraries > Link to the mcs/docs/apidocs documentation from the current Mono > documentation project > 5. Example applications > -------------------------------------------------------------- > A basic tutorial page, in my opinion, should contain the following: > Heading > Description of the topic > C# syntax > More detailed notes, perhaps things that advanced users may be concerned > about, such as possible hidden performance implications such as > automatic boxing that may not be apparent to new users. > C++ users note: Some notes that C++ developers converting to C# should > be aware of. > Java users note: Some notes that Java developers converting to C# should > be aware of. > <other languages conversion notes? > > Program example: small example program that illustrates the topic being > described. > See Also: Links to other topics that are related > --------------------------------------------------------------------- > Possible XML format for tutorial page: > <Tutorial> > <Topic> > <Heading> </Heading> > <Description> </Description> > <Code> </Code> > <Detail> </Detail> > <OtherLang> > <Cpp> </Cpp> > <Java> </Java> > </OtherLang> > <Example> </Example> > <SeeAlso> </SeeAlso> > </Topic> > </Tutorial> > --------------------------------------------------------------------- > > _______________________________________________ > Mono-docs-list maillist - [EMAIL PROTECTED] > http://lists.ximian.com/mailman/listinfo/mono-docs-list _______________________________________________ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
