[CCC DEV] WWW Infrastructure

[Matt Jadud]

On Thu, Oct 27, 2011 at 11:18, Jon Simpson <me at jonsimpson.co.uk> wrote:
>> typeset reasonably correctly without it being a pain). However, I
>> can't solve that quickly, but I can work with the LaTeX I already have
>> in GitHub.
>
> I'm interested in this - what's running now was designed to go some way in solving this problem. Could you expand further/more concretely on what good looks like for you in terms of process & technologies for getting content onto the website(s) ?

[Braindump coming... expect some disconnects from reality and extreme
fantasy ahead... :D]

Well, I'm (1) busy and (2) lazy. And I've used and/or written a fair
number of HTML rendering frameworks over time, and have been reduced
to preferring Sandvox and/or Wordpress (if I need
dynamics/server-hosted tools). Why? Because they're simple/dumb.

Right now, to update the site, I need to:

1. Run my own server.
2. Update content, possibly involving HTML work.
3. Test.
4. Commit.

Steps 1 + 2 are currently part of my issue. There's a confusing blend
of tools that I don't fully understand (my fault, yes) that do not
have a clean separation between template and content. As a result,
there are pages that have (I think) too much HTML in them. This just
might be because they warranted a new template, and that didn't happen
(because I was writing them, and didn't know what to do.)

This framework is also not something I really want to 1) document and
2) maintain and 3) try and teach students and/or community members to
use if they are to contribute (say) documentation, blog posts, or
anything else. Making documentation and web contribution a near-zero
barrier to entry for participation in the overall project is, I think,
a good idea. (Not something we've ever really talked about, but
something I've learned through my participation over on
teachingopensource.org and taking part in workshops w/ faculty
regarding FOSS participation.)

Currently, we run a custom server app for reasons I don't understand.
I think I'd prefer:

1. Wordpress (which everyone in the world understands) if we must run
a server app, or

2. A static rendering framework that can be easily set up on Mac,
Windows, or Linux.

W.r.t. point #1, I'll settle for any hosted CMS that is easy to use.
Drupal, etc. I'm not actually religious about Wordpress. (It is
really, really common, though.) We have people who have contributed
code to the project as occam libraries, but they can't create a page
anywhere that talks about it. I can give people a branch (or space in
the community/ portion of the SVN tree), but to edit the website, they
need a fair bit of coaching. I think this should be easier.

I'd write things like the cookbook directly into the website if it was
as easy to do as using LaTeX. This implies:

1. Presentation is mostly divorced from content.
2. Adding new macros for complex rendering needs to be easy.

\newcommand{\INT}{{\type INT}\xspace}

or similar.

3. Hyperlinking to sections based on semantic labels (which are
resolved by the rendering engine) would be ideal. Eg.
\ref{some-section}.

4. Static rendering is nice, preferably through a selection of
templates/stylesheets. (That is, I'd be happy if it behaved more like
a compile at render-time than a server that does live
interpretation/compilation of the markup.) Nothing we're doing
requires dynamics. Even our link to the most recent binaries can be
resolved statically---we just re-render the site when a new binary
goes up.

5. We need to consider/discuss whether a live, community-editable
portion of the site is necessary. Should there be a wiki? Or, can we
make it easy for people to edit the content of the site some other
way. (If it were all in github, spot editing could actually take place
directly in github. Someone could fork, edit, and pull request
directly through the web interface.)

This is mostly fantasy; in the end, I just don't have everything set
up, and I don't update the site often enough to remember what I need
to do. So, there's a certain amount of laziness on my part here. That
said, we have some template refreshes carried out by design students
last year, and another student has actually worked on scripting the
conversion our LaTeX documentation into XHTML for inclusion in the
site... but, it might just be easier to write in a format more
amenable to this in the first place.

So, you tell me how much of this is laziness on my part, and how much
of it is that we might find a simpler way to render out the website. I
do think that making it easier for me to (say) assign writing some
pages into the site as part of a student project would be a great way
to 1) let students contribute to the project and 2) exhibit their own
work publicly while 3) increasing the value of our web
presence/overall project would be a Good Thing. And, right now, there
are too many steps involved for me to expect a second-year student to
do all of this while also learning a new programming language and
hardware for the first time.

Git is an acceptable barrier (because it is a "tool of the trade"),
but I think running custom servers (that require packages that may, or
may not, install under their accounts in the department, and may not
run because of extreme port lock downage)  just so you can check your
changes is something that I worry about.

You'll find plenty of holes in what I wrote above, but like I said...
it's just me dumping state; push back/brainstorm where appropriate.

Cheers,
Matt