Want documents? Help us! - XOOPS - XOOPS News - XOOPS Web Application System

XOOPS

News

News World of XOOPS Developers Hacks Themes Archive Submit News

XOOPS: Want documents? Help us!

Posted by: hsalazarOn 2003/11/23 23:56:40 5163 reads

Dear friends of Xoops:

It's time to begin formal work in the documentation process, so this item has a double purpose:

1) To share with the community a draft of the Documentation Roadmap asking for comments. Please read the document and take into account it's only a draft.

2) To ask from the community help. The Xoops Documentation Team has at the moment 4 members, and we need some more, as you will no doubt see when you read our aspirations. If you feel you can help, please contact me.

Any constructive comment will be welcome. Any destructive comment will be ignored.

Cheers.

The comments are owned by the author. We aren't responsible for their content.

Re: Want documents? Help us!

Herko Published 11/24/2003 9:05 XOOPS is my life! Joined 02/04/2002 Comments 4238

Documentation is one of the most important areas of XOOPS right now, IMO. Everyone is requesting good clear tailor-made documentation, now is the time to start making some!

Join the Documentation Team and make XOOPS the best and most friendly CMS there is

Herko

Re: Want documents? Help us!

dooder Published 11/25/2003 18:01 Just popping in Joined 09/03/2003 Comments 11

Hi hsalazar,

I like the look and the content of the document you put together. Very slick and inviting to read. Also, I just love to see semicolons used to good rhetorical effect!

I have two comments:

1) New versions of XOOPS will be released which will outdate the documentation. This issue is not addressed in the paper you wrote. I feel the version should be indicated in the naming convention. Also, the versioning and branching of documents needs some outlines. For instance, do you update documentation with inline corrections and amendments showing or do you simply write over the old?

2) There seems to be a certain amount of redundancy in the coverage of installation and "getting going". The document specifies two groups Users and Newbies and looks like it gives both of them the same instruction set. I would argue for making one set of installation and usage docs that have good coverage for all user levels rather than splitting effort into two. The same comment applies for many of the other overlapping documents specified for Users and Newbies both.

Thanks!
dooder

Re: Want documents? Help us!

hsalazar Published 11/25/2003 22:59 Just popping in Joined 02/06/2003 Comments 78

dooder:

The points you raise are indeed interesting, but I must reply they were not overlooked. Let me be more specific.

1) I'm well aware of the transitional nature of every XOOPS version, and also of the transient nature of whatever documentation we generate. Believe me I know: I wrote a while back a small visual guide for Tiny Content that is now badly outdated --even though I used TC 1.2 and we're only in TC 1.5!

This issue is handled in the Documentation Roadmap twice: first, HTML is defined as the "basic format", meaning we intend to be as up-to-date as possible in the HTML version, and only consolidate to physical versions every once in a while.

Second, the document nomenclature does indeed have at its end a number in the format X.XX indicating the document's version.

Now, I guess you're talking about including the XOOPS version in the document name, and that's an interesting idea whose ramifications I'll explore. Thanks for this idea.

The convention needs a bit more structure, I know, so there's a clear logic on it. It's on the works.

We'll have a several-steps process to generate new documents, and we'll keep outdated versions of them, not necessarily online. In any case, whatever document we make available online will have a clear description of its version, of the XOOPS version it applies to and whatever information is needed so users know what they're downloading.

2) There IS redundancy in the list of documents regarding installation and operation due to the simple fact that many people stumble on the installation process. This IS different from stumbling in the *construction* of a XOOPS site once the core is installed.

The difference between the document set for regular users and for newbies lies mostly in the visual load of the documents. The idea is that regular users are familiar with many things so their documents will be more like reference docs. In the case of newbies, the idea is they need to proceed a step at a time, and for this we'd like to have step-by-step, visual tutorials. Then again, you're right about the effort involved. For the doc team, the easiest solution would be, of course, tu build a huge online XOOPS Bible and let the users find their way there, but I don't favor this approach in this case.

Of course we'll start with some basic documents and work our way from there. It's just that I felt the need to have a panoramic view of a desirable state, in order to have a horizon to follow.

Thanks for your comments.

Cheers.

Re: Want documents? Help us!

robekras Published 11/26/2003 6:40 Documentation Writer Joined 12/10/2002 Comments 187

One question about the "basic format" of your documents. You talk about a HTML version which should be as the up-to-date version, and about physical versions.

In your XA-0001.pdf you talk about four different
document output formats (or basic formats?), and how difficult it is to have all four formats.

When I think about a document format, I think about XML as a basic format.
In particular Docbook XML.
With Docbook you can very easy (in theory ) generate PDF, HTML, RTF.

When talking about file naming convention for documents, what is about pictures?
E.g. we have screenshot pictures from different versions, different moduls etc.

Re: Want documents? Help us!

hsalazar Published 11/26/2003 10:01 Just popping in Joined 02/06/2003 Comments 78

robekras:

You're correct as to the versatility of using XML as the basic format, rather than HTML. This is what I mean when I say I need help. My competence is not technology but content; that is to say, I'm more a writer than a techie, so whatever help anyone can provide here will be welcome. And by "basic format" I meant the way users will see the docs. To be honest, my "basic format" is still ASCII text (lol).

In any case, your comment raises a very good point about the general documentation strategy when it comes to products. Because something I also missed in the original version is the fact that, for instance, Word documents have different capabilities than, for instance, CHM files. So probably we'll need to decide which documents should be multiformat and which ones can have just one format.

The proposed convention lists a document version rather than the version of the documented software, but in fact we'd need to make it very clear what we're documenting. This also applies to the screenshots. If the document has a version 1.10 and talks about Module Whatchamacallit version 2.34, the images within should correspond to that version.

Thanks for your comments.

Cheers.

Re: Want documents? Help us!

robekras Published 11/29/2003 12:44 Documentation Writer Joined 12/10/2002 Comments 187

Horacio:

I'm more a techie and so I'm less a document writer.
(Not to say that I don't like writing documents ).

I'm not sure whether I can help you with writing documents (maybe it's worth trying it?).

Every document format has his pros and cons.
So I want to give you some explantions about docbook XML (Excuse me, if you already know that all)

Pros:
- Basically XML files are written in plain ASCII or UTF-8 and of course others)
- XML files could be handled as text files within CVS. Which makes versioning, concurrent editing etc. easier.
- Docbook XML could be easily converted to HTML (single file or chunked), CHM, PDF.
- Automatic creation of XML should be very easy. E.g. for automatic compiling FAQ, troubleshooting, etc. documents (out of a database by script)
- platform independent

Cons:
- Although there are some XML editors available (commercial and open source), for most people editing XML is not as easy as editing with an WYSWYG editor.
- You have to learn (and check up) the docbook tags.

If you are using Windows, I could provide you with some basics about setup a docbook environment.
I also could provide some sample documents and batch files for running the conversion to HTML, PDF and CHM.

Hope you've got some response for your documentation working group.
I also think that with a documentation, as described within your roadmap, XOOPS will make a great jump ahead.

Robert

Re: Want documents? Help us!

hsalazar Published 11/29/2003 16:00 Updated 11/29/2003 16:01 Just popping in Joined 02/06/2003 Comments 78

Robekras:

I've already 9 members in my team, but of course you're welcome to participate if you want to.
As I mentioned before, I love the possibilities of reusing content for different formats, yet I have to take into account a help file, an online document and a physical document have different internal logics, so the issue becomes one of finding the right balance betwen working less and providing a more adequate document for the medium.
I use Windows, and of course I'd like to learn how to setup a docbook environment. Whatever help you can provide in this respect, I'll appreciate.

Cheers

Re: Want documents? Help us!

pstrasma Published 12/24/2003 0:33 Just popping in Joined 12/23/2003 Comments 24

A very nice and ambitious road map. Two questions came to mind reading it though:

1) Wouldn't improved contextual help cut down on the need for formal documentation?

2) What about end user documentation (i.e. stock FAQs about BB posting or news module administration)?

I am getting ready to roll out my first site to a broad user community and am very concerned about #2 as I attempt to move from a single architect to a administration team.

Login

Username

Password

Remember me

Search

Advanced Search

Donat-O-Meter

Stats
Goal:	$100.00
Due Date:	Apr 30
Gross Amount:	$0.00
Net Balance:	$0.00
Left to go:	$100.00

Latest GitHub Commits

{{ record.sha.slice(0, 7) }} - {{ record.commit.message | truncate }}

{{ record.commit.author.name }} {{ record.commit.author.date | formatDate }}

XOOPS: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Re: Want documents? Help us!

Login

Search

Recent Comments

Re: XOOPS 2.5.11 Final Released

Re: XOOPS 2.5.11 Final Released

Re: XOOPS 2.5.11 Final Released

Re: XOOPS 2.5.11 Final Released

Re: XOOPS 2.5.11 Final Released

Who's Online

Donat-O-Meter

Latest GitHub Commits

{{ record.sha.slice(0, 7) }} - {{ record.commit.message | truncate }}

Archives

News archives