Documentation Coordination

frold · Post by **frold** » Mon 3. May 2004, 13:02

Great Oliver.. I will do what I can to help.. so this project can go to level 2 = better docs...

You got my vote

Post by **Oliver Georgi** » Mon 3. May 2004, 13:04

No - new website will start within some days (maybe next weekend).

Oliver

alexander · Post by **alexander** » Mon 3. May 2004, 13:11

I would have fun being the docu admin if you don't already have a person in mind for that job.

But whoever will do that job, he should probably post a "call for documentation" in this forum?! Maybe some people already have some work done, something they can submit - maybe just a quickstart guide or a checklist or anything. I might get done with a "backend user manual" this week myself.

I think we should start collecting what we have. There has to be something out there already.

Cheers,
Alexander

Post by **Oliver Georgi** » Mon 3. May 2004, 13:35

First we have to define rules for documentation and I will create a template for usage in Word and/or OpenOffice.

Oliver

alexander · Post by **alexander** » Mon 3. May 2004, 13:49

Great! What could be the rules? Clear language, keep it short and simple, screenshots should only show what is necessary (not the entire screen) and so on?

A template sounds good. I think, submission should be in either of these formats: RTF/RTFD, SXW and/or PDF. I could offer PDF conversion for those who can't or don't want to do that. Or do you think an HTML version on phpwcms.de would also or alternatively a good idea?

Alexander

Post by **Oliver Georgi** » Mon 3. May 2004, 14:17

I think about automatic conversion from SWX to HTML. That's the best doc format for such things.

But maybe...

Oliver

alexander · Post by **alexander** » Mon 3. May 2004, 15:55

If that's easily done, go ahead... but I don't think you need to put that much effort into it. I think it's not a problem to manually copy&paste a given Word file into phpWCMS so it is available right on the phpwcms.de-documentation site.

What are your thoughts about the documentation rules, though? And when do you think you find the time to design those template(s)?

Alexander

jmeyknecht · Post by **jmeyknecht** » Mon 3. May 2004, 20:28

why not doing documentation with docbook-xml?
so the rules where given by the dtd and we could easily transform it into web (html) and print (rtf, pdf)?

tell me what you all think about it.

Post by **Oliver Georgi** » Mon 3. May 2004, 20:37

sorry - DocBook is too difficult to understand for fast usage.

Or is there a downloadable editor for every platform?

Oliver

jmeyknecht · Post by **jmeyknecht** » Mon 3. May 2004, 20:51

when i worked with docbook, it always used XMLmind XML Editor.
it is java based, so it should work on other platforms too.
but i just worked with the windows version.

maybe someone has also tried this editor? and on another platform than windows?

http://www.xmlmind.com/xmleditor/features.html

Post by **Oliver Georgi** » Mon 3. May 2004, 21:03

I have checked - and I think it is too difficult for most users. Everybody knows how to handle a word processor - so this should be enough.

Oliver

jmeyknecht · Post by **jmeyknecht** » Mon 3. May 2004, 21:07

ok, no problem. it was just an (for me interesting) idea.

maybe you are right, but then "we" have to think about own documentation rules.

Post by **Oliver Georgi** » Mon 3. May 2004, 21:11

that's what I told some...

alexander · Post by **alexander** » Tue 4. May 2004, 14:27

Interesting idea, jmeyknecht, but I agree with Oliver that it should be as simple as opening a standard text editor for the folks who want to write some documentation otherwise the base for contributing documents will be too small.

So, let's think about what rules should apply for people who want to write documentation. As I said, I will have to write some form of "backend manual" this week, so it would help me if I could already do it in a form I can later-on publish on the new phpWCMS-Website.

Cheers,
Alexander

jmeyknecht · Post by **jmeyknecht** » Tue 4. May 2004, 14:44

hehe, I'm trying to implement docbook into OpenOffice.org
maybe this solves our problem of finding rules.

in my opinion it's better to have rules defines by programs, because they are hard to break. the disadvantage of using Word or OpenOffice without program defined rules is, that people will ignore them after a certain time. i hope this won't happen to this project ;-)