[open-data-manual] Options for text management system for Open Data Manual

[David Nind]

Hi everyone.

Other options to consider:

   - Publican (used by Redhat/Fedora for their documentation) - haven't used
   it before, uses docbook, maybe a bit too 'heavy weight'
   https://fedorahosted.org/publican/
   - Drupal - using book feature, HTML output, maybe a little light
   weight/not exactly the right tool for documentation - it does have the
   'social features' though e.g. commenting, enabling editing, RSS feeds etc,
   however it can be a bit more complex to setup  (I am a Drupal fan by the
   way!)

The type of tool you use depends on the focus you want - having a well
managed manual, making it easy to contribute, having the flexibility to
produce multiple formats in multiple languages from a single source, or a
balance between these.

If Sphinx is working well then I wouldn't change it for the immediate
future.

I think the team has done a great job with the manual.

The other thing I would suggest is developing a 'documentation plan' - but
you may have developed this already.

About me: I am new to open data I would like to help where I can with the
manual.  I only do occasional technical writing as part of my role where I
work.  I work for the government in Wellington, New Zealand.  I'm not an
expert in either open data, or technical writing....

Regards.

David Nind
______________________

Email: david.nind at gmail.com
Twitter: @DavidNind
Linkedin: http://nz.linkedin.com/in/davidnind

PO Box 12367
Thorndon
Wellington 6144
+64 4 9720600 (home)
+64 210537847 (cellphone)
+64 4 8906098 (work)



Message: 1
> Date: Thu, 7 Jul 2011 09:42:33 +1200
> From: Tim McNamara <paperless at timmcnamara.co.nz>
> Subject: Re: [open-data-manual] Options for text management system for
>        Open    Data Manual
> To: rufus.pollock at okfn.org
> Cc: open-data-manual at lists.okfn.org
> Message-ID:
>        <CA+YLJLs90rdm-mNmryHhN7rMCVJ+otYqBRGgDvV3uKwDpkyM7w at mail.gmail.com
> >
> Content-Type: text/plain; charset="utf-8"
>
> Sorry for taking a while to get back to you on this Rufus, the mail slipped
> by unread.
>
> On 17 June 2011 02:47, Rufus Pollock <rufus.pollock at okfn.org> wrote:
>
> > I know we had a discussion earlier on about text management options
> > for the manual. Could you post these on the wiki (I seem to have
> > mislaid the location).
> >
>
> I'll do this today. In short:
>
>  - Sphinx
>  - Pure Wordpress
>  - Booki/Objavi, the system behind FLOSS Manuals
>  - GitHub wiki
>
>
> > Also I'm wondering whether a dual wordpress + sphinx option might not
> > be good. We just use wordpress for frontpage and possibly new updates
> > and use sphinx for manual itself. Url setup would be like:
> >
> > http://opendatamanual.org/ <- wordpress
> >
>
> The idea of having a CMS at the landing page is quite neat. It also
> provides
> us with the ability to guide people to the right manual, especially if
> there
> are multiple languages and so forth.
>
>
> > http://opendatamanual.org/en/ <- english version of manual
> > http://opendatamanual.org/de/ <- german version of manual
> > etc
> >
>
> +1
>
> Sphinx doesn't seem to provide I18N support. If localisation is important,
> then I think we should make sure that we use a technical tool which
> supports
> gettext or something similiar.
>
>
> > Alternatively if we cannot have different langs at different urls
> > (still not completely clear on i18n for the manual) we could have:
> >
> > http://opendatamanual.org/m/ <- the manual itself
> >
> >
> "m" is heavily associated with mobile. Maybe integer increments? That way,
> we can release new editions without breaking links.
>
>
> > What do people think?
> >
> > Regards,
> >
> > Rufus
> >
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <
> http://lists.okfn.org/pipermail/open-data-manual/attachments/20110707/fa648ca2/attachment-0001.htm
> >
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/open-data-handbook/attachments/20110708/d13049d0/attachment.html>