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

[Gustavo Ramos]

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.

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?

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.

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.


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?

Thanks in advance,


Gustavo Ramos <eureko@grmexico.com.mx>
People make things just when they want to do it. Let's incite them to
want, and they will be doing what you want.