Hi gang:
After moving the code and the tickets to GitHub, let's make plans for
the rest of Trac site <http://invenio-software.org/>, notably wiki.
There are several categories of wiki pages we've been having:
(1) There are user-facing pages like Demo, Download or Features, like:
http://invenio-software.org/wiki/General/Features
(2) There are administrator-facing how-to recipes like:
http://invenio-software.org/wiki/HowTo/HowToChangeSiteName
(3) There are developer-facing technical documentation pages like
BibFormat system design:
http://invenio-software.org/wiki/Development/Modules/BibFormat/SystemDesign
(4) There are developer-facing RFC pages like:
http://invenio-software.org/wiki/Talk/JSFrameworks
(5) There are user-facing module overview pages like:
http://invenio-software.org/wiki/Development/Modules/BibIndex
(6) There are developer-facing personal overview pages like:
http://invenio-software.org/wiki/Team/GrzegorzSzpura
Here are possible actions on them:
Ad (1), move these to a new attractive Twitter Bootstrap powered web
site for the project, like https://atom.io/
Ad (2), these are collaboratively edited guides, aka real wiki pages.
Move to GitHub Wiki? GitHub pages? Other CMS?
Ad (3), these could come either built-in with the module sources (in
reST), or else they may have evolved from earlier RFC, see next point.
Ad (4), we currently have some RFC-like discussions happening:
(4a) via wikis, the old style, for example:
http://invenio-software.org/wiki/Talk/JSFrameworks
(4b) via GitHub issues, for example:
https://github.com/jirikuncar/invenio/issues/189
(4c) via Forum discussions, for example:
https://forum.invenio-software.org/t/is-pep257-good-for-you/39/last
It would be good to standardise upon channels.
For example, our technical documentation (and wiki) can use reST markup
so that it would be easy to promote/demote documentation and move pieces
of them between RFC, wiki, and code. From this point of view it may be
advantageous if RFC uses reST that too. One way to achieve this would
be to put long write-ups on GitHub Wiki and discuss them elsewhere, on
Issues or on Forum? Another option would be to not bother with markup
synergies at all, and simply use Markdown and discuss RFCs either on
Issues or on Forum? In fact, do we already prefer Issues or Forum for
RFCs? These kinds of questions.
Ad (5) and (6), these could be auto-generated on the new user-facing
site (see (1) above) from GitHub.
Anyway, this was just to outline possible ideas that would be good to
discuss e.g. during today's developer forum. My rule of thumb would be
to reuse as much of existing project tools, and as much of existing
markup, as conveniently possible.
P.S. Here is example of a project using GitHub wiki extensively:
https://github.com/snowplow/snowplow/wiki
Best regards
--
Tibor Simko
