Documentation challenges

posts: 10 United States

Two pages to look at (for discussion): FeatureX and DocConventions.

Here's my quick take on the challenges we face:

(1) The documentation is not discoverable from the tw.o menu. We need a custom menu for the documentation.

(2) Marc developed a rather complex (and I think somewhat inflexible) plan for differentiating among the various types of documentation pages (FeatureXGloss, FeatureX, FeatureXDoc, etc.). We need to decide whether we should consistently follow this or make changes. Taking a cue from Apache, MySQL, and PHP docs (and others), I prefer a more flexible approach with the following sections:

getting started tutorials (admins)
getting started tutorials (users)
reference (users)
reference (admins)
reference (devels)
how-to (i.e., for setting up a new site with the features you want)

The part that Marc's nomenclature described is the reference manual (user and admin version).

(3) The various contributions need to be collated into (I think) html pages (zipped) and pdf. Perhaps the developers could write some code to output these from Wiki structures - they've talked about it, I think.

My big concern is that people are going to start writing stuff using a page nomenclature that will later require a huge reorganization.

posts: 1001 Canada

Quick answer

1. I like the idea of a tutorial module
Let's brainstorm some content :
About Tiki
What's a Wiki
Help about this feature
add your ideas
This had the advantage of being extremely simply removable from the interface.

2. I don't think Marc's way is inflexible.
Actually, we already have the InstallGettingStarted for admins (should probably be renamed GettingStartedAdmin)
I don't think we have a GettingStartedUser (Doc-nothing?) yet, please correct me. This will be a must, but it doesn't need a change of marc's nomenclature IMHO.
Also we have a GettingStartedDeveloper as HowToDev.

I just changed our HowTo page to Archive(HowTo) because it was outdated. See there if you get an idea, though I'm not sure what you mean by HowTo.


I'm waiting other people's repliessmile

posts: 1001 Canada

Hi PocketAces,
this is just a tip about how to contribute to the project.
Since there are too many things to change in Doc, it's useless to throw small ideas like these for approbation. If you red DocConventions and etc. pages, and think a change should be made, you should do it, and in case of doubt, you can always give us a notice here (or in the edited page itself) about why you made the change.
Otherwise there would be too much requests like these to treat.