OK, so here are problems I understand. Once nice docs exist, it's hard
to get them to m.o.
-- learning CVS is a burden
-- using CVS is awkward -- hardware, bandwidth requirements, etc.
-- finding a location is difficult/impossible due to current poor
organization
-- maintaining the pages is time-consuming
I understand the desire to set up an over-arching structure for everyone
to solve the problems. But this is not the approach which prospers in
the rest of the project, our rules and structures have grown
incrementally. I was deeply involved in the implementation of some of
the basic rules on the development side -- super-review for example --
and it is very, very difficult to people to accept and implement such
rules.
Is it possible to take incemental steps? For example, perhaps a
documentation effort could do some of the following:
-- Take a core set of people and explore Doctor.
-- Emulate bugdays with "Doctor day" on IRC and teach people to use it.
-- Encourage people who have corrections to documents to join you and
help them get those corrections made.
-- Identify a few people who are willing to check docs into gila for
other people.
As to the need for better organization for the docs, I absolutely agree.
Your experience in indexing the dom docs will probably occur again
and again. But perhaps your solution is the most likely way to make
progress. When the organization is bad enough that it doesn't work,
someone is motivated to fix it. It's a messy solution, I agree. But it
seems no less ikely to occur than finding someone to reorganize
everything and do it well. Perhaps it would be less painful if staff
showed some appreciation, or even helped ;-)
(fwiw, I personally hate the CVS burden for documentation.)
Mitchell
Fabian Guisset wrote:
>
> This has been said before but here I go again:
>
> There are two main points to my critics against the current mozilla.org:
> difficulty of use, and the lack of structure. Here's why.
>
> Some time last year, I wrote a few documents about the DOM (both code
> doc and usage doc) (see http://mozilla.org/docs/dom). Everything was
> fine until I had to find a place to publish them. First I put it on a
> test account I had a on a free site. FTP and stuff, still good.
> Then I was asked to publish them on mozilla.org. Great I thought, that
> should be easy. Well nay.
> Leaving aside the new hardware and software (bigger hdd + linux cuz I
> couldn't use CVS on windows for whatever reason) I had to get, I had to
> apply for a CVS account, learn CVS, download the good module of the
> website through CVS (luckily I have the cable), and find a good location
> for my docs.
> This last point being so difficult that I ended up creating from scratch
> index pages for /docs/dom. Then came the time to maintain the pages. I
> had to keep my gila tree up to date and make sure that the site actually
> built (this is a website not mozilla) before checking in new files.
>
> The new doctor feature probably makes it a little easier, but nobody
> knows about it.
>
> I did all the above in my spare time and got little to no help (thanks
> Gerv though).
>
> My second point is that I have seen _at least_ 10 documentation writers
> (even professional ones) proposing their help in this very newsgroup.
> The only mozilla.org staff member who ever answered was Gerv. But he had
> nothing to answer, because there was no structure for the documentation.
> I do not see myself telling one of those writers with a full-time job
> "write a document about I-don't-know-what then do everything I did (see
> above) to publish your doc". The net gain from these 10-or-so writers
> was zero.
>
> This is the very reason why I work on moz.zope.org. dbaron will repeat
> that developers know cvs and that developers are those that should be
> writing documentation, but I think by now we have to admit that Mozilla
> developers do not write documentation. Either because the documentation
> structure sucks, or because they just don't want to. In the first case,
> moz.zope.org will make the structure much better and easier to use. In
> the second case, we will not turn off non-developers who want to write
> documentation just because cvs is so inaccessible for them.
>
> The conclusion is, even if we don't need strict style guides and
> spelling guides quite yet, a structure and a better framework are, imho,
> required in order to bring developers and contributors who will write
> documentation. It is naive to think that people will write documentation
> just because you ask them.
>
> I hope you see my point of view,
>
> -Fabian.
>
