[Mono-docs-list] Re: Organizing docs, DocBook?

[Martin Willemoes Hansen]

On Wed, 2002-12-18 at 01:52, Felix Faassen wrote:
> Hi Norman, Martin and others,
> 
> First of all let me say this, because I don't want to give the wrong
> impression and I don't want to be cocky ;-)
> 
> These are just ideas I have in order to get to start working on the
> documentation.
> I just want to sort some things out before I'm going to spend time on
> writing anything and I want to be sure there
> aren't all ready people working on this.
> 
> So please see this post as "in my humble opinion" hehe, okay enough
> disclaimers...
> 
> 
> As for now I understand there 3 types of categories when it comes to the
> documentation:
> 
> - Class Library documentation (API docs)
> 
> - Manual based documentation (Overview, Installation, Getting Started, MONO
> Architecture,Tools, Resource etc.)
> 
> - Referenced based documentation (FAQS, HOWTO's TUTORIALS)
> 
> 
> * Class Library Documentation
> If I understand correctly there are tools currently in development in order
> to facilitate
> a documetation system in regards to the class libraries. This part is all
> ready covered by the MONO DOC specs and supporting tools. I also read that
> class contributors are submitting the documentation as well.
> 
> * Manual based documentation (Getting started/ Redbook/ Overiew etc.)
> As for now I have not found any document which gives a complete overview on
> MONO, which describes steps how
> to install (win32/linux/etc) how to get started etc etc. There are some
> FAQ's and tutorials which cover these
> topics but I have yet not found a central document.
> 
> I think it's a good idea to create a general document which is considered a
> manual to mono. This document should focus on
> getting people started with mono and give them overview of what's out there
> and how to use it. Furthermore it should
> reference to other resources on the mono website and of course the tutorials
> on. Norman and I had the idea of using the table of contents, posted earlier
> on the docs-list and work out, we both make a TOC, post it and try to figure
> out (together with other list subscribers) a general TOC so we have a tree
> where we can write on ;-)
> 
> 
> * Reference Based Documentation
> I think it's a good idea to have the turorials seperate from the manual
> based documentation, as we can now see on
> http://go-mono.com/gnometutorial/. I generally like the tutorials which are
> on http://samples.gotdotnet.com/quickstart/
> or http://samples.gotdotnet.com/quickstart/howto/. Actually I just checked
> it out and I'm confused, how do we call
> this a HOWTO, tutorial or quickstart ;-) heheh doesn't matter I hope  you
> get the idea
> 

Maybe it would be a good idea to make a howto make documentation, just
like you have outlined above, it would give people who wants to help in
this cause a much needed overview :o)

> * Documentation system/format
> I looked into the MonoDoc XML specs. Correct me if I'm wrong, but as written
> on the mono site MonoDoc is the format for multilingual API documentation.
> 
> As I've written earlier I haven't got any experience with publishing
> systems. But as I can see Docbook is the way to go, right? Martin what have
> you used to create the tutorial?

We are using plain html. At the beginning we had big arguments about if
we should use docbook or whatever, it boiled down to something like
almost nobody of us had used docbook and that it was kind of hard to get
going also the benefits we could harvest was pretty small.
So basically we just write in html, everybody knows it and we get work
done. 

> (About this having no experience with publishing systems I'm working realy
> hard to get a grip on DocBook)
> 
> Okay enough ideas. I'm working on the TOC, as soon as it's finished I'll
> post it here. I also start to look into creating a docbook. Any suggestions
> about the docbook issue?

Cant wait to see your TOCs

> Take Care,
> 
> 
> Felix
> 
-- 
Martin Willemoes Hansen

--------------------------------------------------------
E-Mail	mwh@sysrq.dk	Website	mwh.sysrq.dk
IRC     MWH, freenode.net	
--------------------------------------------------------