Richard, your work is a blessing I think we should just go with this and implement it (aka use it for a module).

Herko

News 1.3 will be soon released, may be it could be the opportunity to use Richard's work. But I'd like to have some help for this.

Bye,
Hervé

At the moment I am pretty well maxed out on running the FAQ and raising its profile on the site. This is an important aspect to 'documentation'and one that is worth supporting. It's not just a a matter of approving/moderating Q&As.

FAQs give a very direct answer to users enquiries and it's proving very popular however, users need reglar reminders of where to look

The current state of the "Documentation team" is ah-erm ... fairly thin. People change their agendas and priorities and that is just fine. My sincere thanks goes to all of you that have helped in the past, your input was truly appreciated.

BUT, right now we are short of active members in this area. Recently I have had 2 requests to help with documentation from xoopsers and for that I am very grateful. However, if we are to implement a partnership with the QA team (which I feel is essential),we really need more VOLUNTEERS!!

A while back I was looking to import a task manager into XOOPS to co-ordinate the procedures of documentation, unfortunately, this hasn't happened and I'm now looking (cautiously) at xHelp as a possibility for task tracking. I had a go on the first version at changing the "trouble ticket" language to "Task" etc. maybe I should look at this again.

Anyway, this gist of this post is this: If you can offer any help with documentation, just post here, or contact me, We are at a crucial step, with the QA team and new core versions set for release this year. So let's get the ball rolling again .

In a former life, waaaay back when, in a land long ago, I lead the doc team for a little while and we came up with a draft outline/skeleton for Xoopydocs. It should still be floating around somewhere.

Maybe herko has it?

I had a suggestion about how to improve module documentation, but it got pushed off the front page pretty quickly and got no replies

here's the link to that post

Basically I believe module documentation should become a community effort, not rest on the shoulders of one or two people. So I proposed starting a module documentation wiki, linked to the docs site. See the link for details. I'm still interested in hearing what people think about the idea

Rowd

I am not sure that a wiki is the best way to do this.
If it is left up to the community to contribute, it will - no offense meant - not get a lot of input.

Don't get me wrong, I think it is excellent to have module documentation in one place where the general public can also read and comment on work in progress - but making the general public the main contributor, which a wiki is meant for, won't work.

As the proverb goes: If everyone is in charge, noone is.
We need module developers actively taking charge of the documentation of their modules and if others can contribute, that's good, but it is mainly the responsibility of the module developers to make sure their modules are documented. Whatever the documentation team can give of pointers to good documentation practices and structure is good, and a place to discuss "does this make sense?" and similar questions is good. But let us not take away the responsibility from the developers.

Wow! There's lots of interest and ideas about documentation out there, that's great.

I totally second the idea that docs should be a requirement for a certified module.

And I totally second the idea that there should be a template for module docs so it gives developers a place to start, 'cause that's one of the hardest part of writing, figuring out how to organize what you're going to say. A standard framework would really help. I will have to check out the samples suggested here; maybe the Formulize docs I'm working on will follow that format as a test.

Lastly, I'll paste in a link here to a great article mentioned on Slashdot today, where one of the things the author says is that computer science students must be able to write clearly (he says in English 'cause he's in the US).

http://www.joelonsoftware.com/articles/CollegeAdvice.html

Quote:

"The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it's not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless. By writing clear technical documentation for end users, they allow people to figure out what their code is supposed to do, which is the only way those users can see the value in their code. There's a lot of wonderful, useful code buried on sourceforge somewhere that nobody uses because it was created by programmers who don't write very well (or don't write at all), and so nobody knows what they've done and their brilliant code languishes."

Similar things can be said about the relationship between end user docs and the popularity of a module with end users.

--Julian

P.S. I hope marcan or one of the other Quebecers will show up and say something witty about bill 101.

hi all

I have to agree with the complaint about documentation - and you will see I have been contributing where I can - if I face a poorly written read me file - or can't follow what it says I have taken the time to make an inquiry of the documentation author...some have responded well - others not so well. However I was waiting for smart FAQ and have added what came to mind in there - and now am waiting for some way to get involved as invited by Herko I think some time back. I am a senior English/ESL teacher and have a BA in linguistics (study of languages and how they work) so that is my expertise. I am not experienced with the tech language so I bring that focus to document writing. All I need is some direction about what needs to be looked at and checked or corrected. The difficulty might be getting the module developer to work on it after all their work making the module in the first place.

If anyone has documentation they want looked over I would be happy to help - and doc's in foreign languages need to be rudimently translated to english before I can jump in and clean them up.

I do ask however that all modules in the XOOPS repository be accopmanied by a description of what they do - there are so many that do not have this and that is frustrating when looking for a module to 'do something'.

So guys...how do I get on board here???? Can i get off my L plates yet

Cheers

@Mith
That's not quite how I imagined it. I agree module developers need to be in charge of their documentation, but often it's such a huge task that allowing others to contribute could mean the difference between having documentation, or not. And this could also be an answer for developers who are not confident with English.

I know that I once tried to write documentation for WF-Sections beta1, since I know quite a lot about the module after having tested it pretty exhaustively. But when it came to writing it down, there was just so much to cover that I stopped. If there were others also contributing collaboratively then I'm sure there would have been pretty comprehensive documentation available by now.

Wiki's are open to the general public, but each page does have an owner, and the responsibility for the documentation falls to them, not the general public. In this case the module developer would be the owner.

Rowd

Quote:

Jenclas, is that an offer to help? If so, please contact me. We have projects pending that don't require great technical knowhow, just clear concise dissemination of how things work!

Rowd,
I tend to agree with Mithrandir that public collaboration through a wiki leaves much to be desired in terms of style, subject organisation and consistancy of content detail. It's great for collecting ideas, but it becomes over fragmented. Maybe the wiki idea is a good information gathering tool, In that regard, I would endorse your idea strongly, but then it should be followed by editorial refinement and formatting before a publication stage.

To make quality documents, requires a multi-stage process involving close collaboration with the developer(s). When I made the documentation for the SmartFAQ module, it took several weeks working with Marcan to ensure fidelity of content.

The ideal is to release a document co-currently with the beta software, because this is the time when users require the help guidance most. Using a wiki would only work retrospectively after release as users became familiar with software usage. As the software is debugged and refined in the public arena, so documentation should be updated to reflect the changes, until a final is produced.

I strongly maintain that development and documentation should always be a parallel process.

Let us also consider the possibility of embedding 'help' comments in with the source code. In this way the developer can describe exactly what is intended with any particular function. No, not the docbook style, I mean a 'user help popup' associated with a particular link, form or screen area. Take alook at the smartFAQ documentation and imagine something like this here embedded in the page of the actual module!