ProsePoint Express: hosted newspaper website content management software

Documentation wiki?

  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_handler_argument::init() should be compatible with views_handler::init(&$view, $options) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_argument.inc on line 0.
  • strict warning: Declaration of views_handler_filter::options_validate() should be compatible with views_handler::options_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter.inc on line 0.
  • strict warning: Declaration of views_handler_filter::options_submit() should be compatible with views_handler::options_submit($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter.inc on line 0.
  • strict warning: Declaration of views_handler_filter_node_status::operator_form() should be compatible with views_handler_filter::operator_form(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/modules/node/views_handler_filter_node_status.inc on line 0.
  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_handler_filter_boolean_operator::value_validate() should be compatible with views_handler_filter::value_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter_boolean_operator.inc on line 0.
  • strict warning: Declaration of date_api_filter_handler::value_validate() should be compatible with views_handler_filter::value_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/date/includes/date_api_filter_handler.inc on line 0.
  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_plugin_row::options_validate() should be compatible with views_plugin::options_validate(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/plugins/views_plugin_row.inc on line 0.
  • strict warning: Declaration of views_plugin_row::options_submit() should be compatible with views_plugin::options_submit(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/plugins/views_plugin_row.inc on line 0.
10 replies [Last post]
Paul Gillingwater
Paul Gillingwater's picture
User offline. Last seen 7 years 6 weeks ago. Offline
Joined: 05/03/2009
Posts:
Hi, I am prepared to offer my time to help document ProsePoint. To this end, Beng has suggested setting up a Wiki, which I think is a good idea. My only concern is that the Wiki should have an export capability, e.g., to Open Document and/or PDF formats. Is there anyone else who would like to contribute to documentation? cheers Paul
__________________

Follow me on http://www.twitter.com/ahbleza

Michael McCarthy
Michael McCarthy's picture
User offline. Last seen 7 years 18 weeks ago. Offline
Joined: 06/03/2009
Posts:
Wiki
I'd be willing, though I don't know if I fathom ProsePoint enough to be very useful. - M
__________________

Michael McCarthy Editor LocalHealthGuide www.localhealthguideonline.com

beng
User offline. Last seen 4 years 31 weeks ago. Offline
Joined: 27/02/2009
Posts:
I think a wiki or book will eventually happen

Hi,

I think a wiki or Drupal book will eventually happen. If people want to contribute, I should try to facilitate and then get out of their way.

So, let me go consider the implementation options and get back to you.

Paul Gillingwater
Paul Gillingwater's picture
User offline. Last seen 7 years 6 weeks ago. Offline
Joined: 05/03/2009
Posts:
Wiki

Michael, I think ProsePoint is new enough that none of us (with the exception of Beng) are really expert.  This is a learning journey, and I think updating documentation as we get the system to perform is a good approach for other beginners who will come along later.  Think of us as trailblazers, marking trees as we go...

--

cheers

Paul

__________________

Follow me on http://www.twitter.com/ahbleza

beng
User offline. Last seen 4 years 31 weeks ago. Offline
Joined: 27/02/2009
Posts:
The community has spoken

I think the community (fledging though it is) has spoken. Time for me to add a semi-open documentation section to this site (hopefully soon).

beng
User offline. Last seen 4 years 31 weeks ago. Offline
Joined: 27/02/2009
Posts:
Paul, Been thinking about

Paul,

Been thinking about this. Implementation wise, I'm tending towards enabling Drupal's book module on this site, and then allowing people to write their own book pages. It's not quite a wiki in the traditional sense, but it allows for community editing, and that's the functionality that's important.

Anyway, technology issues aside, my concern is regarding who is going to oversee and guide the creation of the book's content. I haven't scheduled in any time or resources to do this anytime soon. Would you be comfortable, and willing, to start and manage the documentation effort from scratch? I'm not sure how much you feel you know about ProsePoint, and whether you think your knowledge is sufficient to act in an overseeing role (in addition to writing documentation, that is).

So, I'm just checking so we don't accidentally end up with mismatched expectations. That's just asking for misunderstandings to develop in the future. Let me know what you think.

Paul Gillingwater
Paul Gillingwater's picture
User offline. Last seen 7 years 6 weeks ago. Offline
Joined: 05/03/2009
Posts:
Drupal Book module as basis for docs

Hi Beng,

I certainly don't claim to be in any way an expert with ProsePoint, let alone Drupal.  I have however worked with several other CMS systems, and have worked with PHP and SQL code for several years, so I am sure I can learn the relevant aspects.  I've also written extensive technical documentation, so I'm not daunted by the task of organizing the structure of the book on ProsePoint.  In particular, I find the taxonomy concepts quite familiar from other knowledge domains.

My goal here is to work with a non-profit newspaper, The Vienna Review (http://www.viennareview.net/) which is published out of the university where I teach.  Specifically, I am building the new foundation to replace the previous CMS (which I also built, based on Redaxo).  I am therefore working with people who are absolutely not technical, but who are experienced with how a newspaper works.

In my view, the documentation for ProsePoint should focus on the tasks of building and maintaining a newspaper or similar periodical, with a focus on editions and regular maintenance of stories and other media.  I feel that it will serve its constituency best when it complements the existing Drupal documentation (which seems to have a more technical focus), and can act as a guide for relative beginners to enter online publishing.

Bottom line: I am willing, subject to time constraints, to take responsibility for coordinating the documentation effort, and will welcome contributions from other writers who have discovered ProsePoint, and have learned how to make it do something "cool."  I think a mix of tutorials, how-tos and reference material will suffice.  Eventually, I'd like to see a dead-trees version appear, if ProsePoint develops sufficient critical mass.  Therefore, whichever platform is chosen for the documentation should support some form of XML export (e.g., to ODF XML), plus PDf generation.

For the text itself, I propose that it be released under the GNU Free Documentation License -- which of course does not preclude commercial publication in future.

cheers

Paul

 

 

__________________

Follow me on http://www.twitter.com/ahbleza

beng
User offline. Last seen 4 years 31 weeks ago. Offline
Joined: 27/02/2009
Posts:
Just looked again at Drupal's

Just looked again at Drupal's book.module, and discovered that is doesn't do any sort of export except for a fairly crude printer-friendly type html version. There is a supposed book export module but that's for Drupal 5.x, and it looks to be an abandoned module, so I don't really expect anything there.

Although, I could eventually write (or find someone to write) some code to export it to XML if need be.

I've opened up the solution space to include standalone wiki's and other documentation solution. Whilst investigating, some things came up with I'd like to see if you have any opinions on.

> In my view, the documentation for ProsePoint should focus on the tasks
> of building and maintaining a newspaper or similar periodical

I agree about this.

> I think a mix of tutorials, how-tos and reference material will suffice.

I notice that in the original post, you've suggested using a wiki for documentation. However, would you consider a docbook approach (which is how I've created the user guide)? With this approach, editing would be limited to certain pre-approved people, editing takes place offline, and there would be more coordination amongst contributors in order to create a more structured (and hopefully, higher quality) deliverable?

The reason I'm pondering this is that, if we keep with docbook syntax, the content can be transformed into any form (ie. pdf, xhtml, dead tree book). However, doing this would limit the pool of potential contributors to those who know how to use docbook syntax (as well as make it not as simple as editing online).

If we stick with the original wiki idea, I suspect that any sort of export of content will be somewhat lower quality because it'll just be a bunch of html nodes with inconsistent formatting and styles.

Or perhaps I'm thinking too far ahead :)

> GNU Free Documentation License

Any individual specific reason for this over creative commons? I'm vaguely aware that GFDL has a recent new version out, so I'll have to go have a second look at it.

Paul Gillingwater
Paul Gillingwater's picture
User offline. Last seen 7 years 6 weeks ago. Offline
Joined: 05/03/2009
Posts:
Docbook XML

I've done a fair bit of documentation with DocBook, and I think it's a fine choice.  I'd be happy to work with it.  There are some decent tools available, and it integrates nicely with many source code revision systems.  What's your preference -- do you use GIT, cvs or somethink based on Launchpad or Sourceforge?

 

__________________

Follow me on http://www.twitter.com/ahbleza

beng
User offline. Last seen 4 years 31 weeks ago. Offline
Joined: 27/02/2009
Posts:
Thoughts ...

Docbook

My preference for a source control system at the moment is bazaar (bzr), but historically, that's only because the ProsePoint code is hosted at Launchpad and Launchpad uses bzr. At the moment, the source content for the ProsePoint user guide is also kept in bzr on my private systems. All things being equal, I'd like to stay with the status quo, but if things are not equal, I would consider something like git or svn (though I consider svn a step backwards from bzr).

If we go with the docbook approach, then the process will be slower than open wiki-style editing, but (hopefully) the content will be more coherent and more suitable for eventual printed publishing.

GFDL

I've been looking at the GFDL in detail, and there are a couple of issues which might make it unsuitable.

The first one is that the GFDL is incompatible with the GPL (which is what ProsePoint is released under). If the User Guide is to be licensed under the GFDL, we cannot place any ProsePoint code into it (and we cannot place any text from the User Guide into ProsePoint either), not even as illustrative examples. Since I foresee a future section in the User Guide targeted at ProsePoint development, this could be a showstopper.

The second point is that the full text of the GFDL (and some other things) must be distributed with all copies of the User Guide, even excerpts. If someone prints out a single page of the User Guide to give to someone else, they are required to also include the 10-ish pages of the GFDL with it. Oh, and they must also provide the docbook source of that page as well. This sounds very onerous.

There are other criticisms of the GFDL in the literature (see http://en.wikipedia.org/wiki/GNU_Free_Documentation_License and follow the cited references), but these are the two main ones I care about the most.