[Radiance-general] Radiance documentation organization

[Thomas Bleicher]

On 4 Nov 2006, at 18:56, Jack de Valpine wrote:

> Hi All,
>
> I just want to follow-up on this a bit.
>
> Clearly there are a lot of CMS options such as Wiki and others
> that have already been mentioned. I think though rather than
> revisiting what tool to use, we really need to focus on what
> content would be valuable, how it is organized and who would
> be interested in producing what content.

I want to support Jack on this point. Though a big part of us
has some experience with setup and administration of some kind
of content management/markup/publishing system we should focus
our discussion on the things we want to see on the system and
the way how we are going to use it, not how this could be
implemented with system XYZ.

In fact, I think that all popular systems will support the features
we need. Since there seems to be a consent about raising and
spending some cash for the setup and maintenance I would suggest
that we create a 'wish list' (specification) and ask a service provider
or consultant to do the configuration for us. This could as well be
something else than Plone, provided that the chosen SP has better
experience with it and can implement our features.

> There is a huge amount of valuable information that gets generated on
> this list. However it is sometime difficult to realize the value  
> because
> one has to dig through email archives.

This could be a possible feature of the new platform. Should the
mailing list migrate to the CMS as well, should we only have a
'connector' to reference and archive emails from the lists or can
we do with a simple externally created digest page for each month?

My personal wish list for the system is this:

1) transparency of content management and storage
    this is more of an admin issue, but should we decide to have
    a hosting solution, guaranteed access to the data and backup
    is a feature we have to request

2) authentication
    could be weak and simple, though, this is mainly to prevent
    excessive spamming and point 3

3) controlled editing
    I like the instantaneous access of wiki pages. But in this
    case I'd prefer to have a dedicated editor for each topic
    who controls and edits the content of the page. I like the
    idea of a 'shadow page' that's open for everyone to write.
    That keeps writers with a short attention span interested.

4) cross referencing
    Judging by our current content structure we will have several
    topics which a dealt with in different places. There should be
    an easy way to navigate between these connected pages. Wikis make
    that very easy - but also very messy. I hope we can find a better
    solution.

5) support for different content types
    there will be at least:
    - plain web pages with images (reference, tutorials, etc)
    - code samples
    - probably quite a few equations mixed in the text
    - PDF and Powerpoint documents from the workshops
    - source code (CVS controlled?)
    - mails (see above)

6) external editing
    Those of us who will write a lot will prefer to use their
    own editor of choice instead of a browser text box. Maybe
    there's a chance for revision control as well.

7) PDF output
    I'd like to be able to 'dump' selected chapters in a PDF
    document. That will make a revised edition of RwR easy -
    and of course useless.

8) email notification/reminders/digests
    basic feature i guess

9) navigation and appearance
    It should be easy for occasional users to find their position
    within the content structure and find related content. It's
    amazing how complicated web pages can be.


In my opinion those are the most important features the system
should provide. Order and relevance is of course open to discussion.
I'm sure someone else will find other features that should be
included or identify some we can do without.

Some of the points above need further detailing (like the editing
workflow) but we could agree on the general functionality we expect
from our new home in cyberspace.


I'm sorry I will be away from keyboard and broadband for the
next week. So please do not feel offended if I can not answer
any replies to this message.

And of course the standard disclaimer:
I'm happy to contribute to the documentation project whatever
I can and in whatever form it will appear.

Regards,
Thomas