Documentation Efforts

To throw the metaphorical match into the fire, what are we doing about documentation?

Simply put, we need more of it and it needs to be updated more often.

Most of us dread documenting (save Susan) so what are we going to do about it?

Go Wiki? Nominate more people to help? What?

<comedy>

7:55 911, how can we help you?
7:55 We need a bigger documentation team
7:55 A what sir?
7:55 Documentation Team
7:55 Sir, how is that an emergency
7:55 We are getting swampted by users for support requests
7:56 I see, but what does that have to do with 911
7:56 Well, they taught us in school to call 911 if we were in big trouble
7:56 Yes sir, but they were referring to life or death
7:56 Well, it is. Except it is a projects life at stake.
7:56 I see sir, I am hanging up now.....
7:56 Wait, wait! We need help!.........

</comedy>

Yeah, I called 911 and got that! *sigh*

....

:P ..

Well, in seriousness we need to work on Documentation and for that purpose we need more contributors, now infact mostly member dont like Wiki, but we need to sort some way out to overcome this.

Yeah well, I agree with you Mark, that’s why I raised the documentation issue in my Status of current projects ? thread.... I also volunteered to help with it.

I have a little documentation experience from my Textpattern days, I was a wiki admin there and the guy in charge of the french doc. It seems documentation is a reccuring problem in many open source projects... contributors are scarce, documentation is rarely if ever comprehensive and, even more, almost never up to date...

The wiki question had been raised, but I remember we had decided against the wiki, since MODx will have revisionning at some point the idea was to avoid transferring content at a later date... plus many team member were not to eager to work with a wiki.

This being said, we have to go forward with this and find a way to make progress, if it means wiki then why not ?

Yet, my main concern is that MODx will (in my understanding) undergo major changes with the 1.0 rewrite. Thus the question is : how long does the current branch has to "live" and should we devote major efforts to the documentation if the 0.9.x branch has a live expectancy of a few months ? It’s either too late or too soon ?

My line of thinking is, maybe if (and only if) 1.0 is not far away, maybe we should wait a little and really boost documentation effort for the 1.0 branch since it seems to be really different than 0.9.x efforts on this branch’s documentation might be lost...

Anyway, no matter what course is taken, I think we should :

1) Have a "Want to contribute ?" page as Zi had suggested time and again, and make clear to community member how they can contribute. Documentation is one of them. We have to give access to the contributors to direct editing of the doc, no matter which tool we use.

2) Involve the forum moderators, especially local communities, which will be a key to having a multi-lingual documentation. The question here will be, should we wait till we have a "stable" english version to get the translating going (to avoid inconsistencies : i.e divergent documentation in different languages.

3) Involve advanced users, i.e ask for their help. Not only do we need contributors to write the doc, but we also need people to cross-read and check things in the doc.

I am happy to work with a wiki. However (for marketing purposes if nothing else) MODx should use core MODx facilities to present documentation to the public.

Quote from: davidm at Jun 15, 2006, 02:23 AM

We have to give access to the contributors to direct editing of the doc, no matter which tool we use.

Yes. But we don’t need to give everyone access to edit, nor to the latest incomplete version of the documentation.

I believe we should think of public documentation as something that is "released", rather than something that is being worked on "live". That way we can release a coherent set of pages which have been "beta-tested". Unverified documentation is worse than no documentation.

Only once we’re all happy with it, does a "documentation release" go up on the main site. Only the final draft is kept, and that becomes the first version in whatever revisionning system MODx 1.0 ends up with.

Further, this means that we can develop documentation in a Wiki now, and transfer only the "final" texts over to the MODx revisionning system. By embracing the transfer of content rather than avoiding it, we’re actually more flexible.

Editing Method #1: A Wiki Pretending Not To Be A Wiki
It is possible to use Wiki software to edit documents without having to go for the whole Wiki mindset, and a Wiki does not mean "like Wikipedia". This, together with the idea of drafting documents for the main site, might help some of the anti-Wiki people come to terms with the idea. Make sure the Wiki home page is a list of all the documentation articles. Some may well be empty.

Editing Method #2: A Messy Free-For-All Forum
Add a forum on here where all approved contributors have Moderator privileges and can all edit the top post of each thread.
Each thread would be a page or section of the documentation.

When to boost documentation efforts
It would be exceedingly helpful if we could know what concepts are retained/expanded in 1.0 and which are dropped. Anything that is retained/expanded can be documented as it stands now in 0.9.x, and then improved later on. Anything that is dropped/significantly changed should ideally have a warning in the 0.9.x documentation so that people can judge how future-proof their code will be.

Regardless of whether we do much 0.9.x documentation, a multi-contributor non-MODx drafting solution needs to be in place for the initial private releases of MODx 1.0. Even if the first release does have revisionning, it will not have been tested. It is probably unwise to write documentation using early versions of 1.0 because things are likely to still be in flux until the final release - and MODx 1 really will need documentation available on release.

So to summarise: definitely use MODx to present documentation to the public, but don’t be shy of using other solutions to draft it.