[Mono-docs-list] Ideas for boosting the documentation effort

[John Luke]

Hello,
	I'll comment inline.

On Wed, 2004-02-18 at 21:37, Gustavo Ramos wrote:
> Hello list,
> 
> Since some time, I've done a bit of work in gtk docs, but I didn't
> posted it because there is a lot of questions for the new contributor,
> and mines did keep me busy looking for more info in the mailing lists.
> Now I have monodoc up and running, and see that it is a lot easier, but
> I suggest some things that happened to me, and could improve the
> documentation effort a lot (keep reading).
> 
> 
> WHY THE DOCUMENTERS SHINE BY THEIR ABSENCE?
> 
> 1) It's not easy for a newcomer (in this case a documenter) to talk to a
> list. They see a lot of high-level questions (about low level bits), and
> a lot of information on the topic out there on the net. Thus, a novice
> is generally scary about a RTFM-like answer.
> 
Anyone interested in documentation should not be scared with asking on
this list how to get involved.  In fact, please do ask so we can help
interested people.  I would love to get more people involved.

> 2) Searching for said things about documentation (like content on web
> pages, wikis, the existing docs and the huuuuuge mailing lists) is very
> time consuming. Not everybody is patient. However, the best place to
> look at is the documentation, generally it is well organized.
> Unfortunately mono documentation is not --by far-- near completion.
> Fortunately, we have monodoc!
> 
> 3) A newbie looks for someone to help him getting started. It's a
> natural condition that needs to be addressed. Looks complicated: Miguel
> has a great lot of things to do. About him and other main
> contributors... their time is precious, it's better to let them keep
> hacking. Some minor contributors... they may not have the expertise (or
> CVS access). And newbies... Well, they are on their own, and at best,
> there is the mailing list; at least until mono dives the version-1.0
> waters. But in the meanwhile, it would be worth to gain hacker time,
> just freeing him from writing docs.
> 
> 
> WHAT COULD WE DO?
> 
> 1) To have a Tag list and other howto-contributing-mono-docs related
> information in a page *inside* monodoc. i.e. what tags should i use in
> the documentation xml? how to post the information? what if i don't have
> monodoc working, and still want to contribute? who is in charge of each
> module/provider/namespace/whatever? A faq, a documentation manual or
> howto, the ecma docs spec, etc. In short, wouldn't be a good option to
> have the documentation effort well documented in monodoc itself?
> 
I like this idea of putting a brief tutorial inside monodoc itself,
containing how to edit and submit the docs and the various tags to use.

> 2) To have documentation managers: Monodoc needs someone to review
> contributions, a more formal procedure, because new contributors can
> feel lost. i.e. The GtkSharp authors/maintainers should coordinate the
> GtkSharp documentation tasks (without spending much time), reviewing
> contributions and or pointing out corrections that should be made to the
> contributions. Maybe minor contributors can made the massive minor
> corrections, freeing the main hackers from trivial tasks. Somewhat like
> the concept of Arturo Espinosa "Cada quien tome a su pupilo" ("Everyone
> take your padawan learner"). People who has cvs write access, should not
> spend too much time reviewing the patches already reviewed by other
> contributors, there's always the cvs-rollback option. I'm not talking
> about rollbacks as a daily task, rather as a "for when it happens"
> option. Delegating trivial work is a great time gain. Again: Documenting
> how this revision procedure works should help the newbie understand
> where, how, with who and when to do docs from now on.
> 
I am not sure why you think this is not done already.  Everything is
reviewed and we do coordinate with Gtk#.  Perhaps because it has not
been discussed on this list it is not obvious that this happens.

> 3) Things in the code that helps the documentation. In addition to the
> [TODO] pseudo-tag/attribute, a tag/attribute for saying who is currently
> responsible for that page (valid for all docs). This should be used when
> someone picks a doc and say: I'll do it. The tag should say when the
> contributor picked up the item and when is the "soft-deadline". This
> soft deadline should not be there for pressure or anything like that,
> rather for finding abandoned docs, and to let the newbie know if a
> [TODO] item is already taken. These tags should help to keep the
> maintainability of the whole thing.
> 
There is gtk-sharp/doc/en/Gtk/TODO which shows unclaimed and
undocumented members of Gtk.  Anything that someone has not claimed
there is available for someone to work on.  There is also the
'maintainer' attribute in the docs themselves for completed docs. 
> 
> I know all this could be done as it has been until now. However there
> are out there a lot of people willing to contribute, and their free time
> could get mono docs done faster, if we help them to make their time
> *usable*. Thoughts?

As I said earlier I would love more people to get involved with the
documentation.  Anyone interested that needs some help getting started
should post here, join #mono on irc.gimp.org, or even contact me
directly and let us know what you need to get started.