OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: DocBook web infrastructure needs work


Hi, I'm new to DocBook.  I'm trying to jump into it, but am having a really hard time.  I've spent an inordinate amount of time just trying to figure out what the latest-and-greatest of everything is, where on the web are the resources, etc., etc.
Here I've jotted a few notes from my newbie perspective, for your consideration:

Here's just a small subset of the sites I've come across:
(1) Docbook project page:  http://docbook.sourceforge.net/
(2) DocBook.org, Norman Walsh' DocBook site
(3) http://nwalsh.com/docbook/, Norman Walsh' *other* DocBook site
(4) DocBook repository:  http://sourceforge.net/projects/docbook/
(A) DocBook Wiki - http://wiki.docbook.org/
(B) DocBook FAQ - http://www.dpawson.co.uk/docbook/

- I'd propose to make the DocBook project page (1) the primary resource for
  people wanting to get involved with DocBook.
    - Right now, in a Google search on "docbook", this site comes up ninth.
      (behind the wiki, the faq, etc.)
    - Norm's site (2) should have a prominent link to it.  Right now, I don't
      know if there's any link at all (but I didn't search exhaustively).
    - Norm's other site (3) has a link to the repository, but not the DocBook
      project page.  Norm, I'd suggest making a link to the DocBook project
      page #1 in your list of "principle sources".

- TDG is very good, and is a good entry-point, but it is a little bit hard to find
  (and hard to know that you're looking at the latest version.)
- But what's really missing is a dead-simple "Getting Started with DocBook
  in one hour" lesson.
- Examples!  I want more examples/templates of complete documents.  These should
  be kept up-to-date, and should showcase as many of the tags as possible, by
  category.
- It seems that the wiki (A) is dead -- so links to it should either be removed,
  or else some other caveat should be given before the user clicks through.
  (At the very least, remove "up-to-date".)
- The FAQ (B) is also badly out of date.  So, ditto with the links to it, unless
  it can be beaten into shape.

Who maintains the DocBook project page?  If anyone's with me here, maybe I
could follow this up with some specific suggestions for improvements to that
page.

 


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]