Rebol.org new design

[BrianOtto]

Here are some screenshots of what I've been working on ...

This one shows the general layout of the Documentation section. An "Add Page" button, top-right, will allow you to build the entire navigation you see on the left (i.e. Welcome, Getting Started, etc). It is fully customizable. You can add / remove any of the links you see there, you can specify the breadcrumbs that will appear, and you can specify the URL the page is located at.

On the right is the content, and it is meant to be a collection of smaller sections, that together, will represent the documentation for this page. You can add as many new sections as you like, by clicking the "Click to Add a New Section" area. You can move them around too, and they can include different types of content like code blocks, images, video, etc. This part is still a work in progress, but it is slowly getting there. Also, the reason the content is broken up into smaller section is so that multiple people can work on different parts of the page at one time.

Another thing you might notice is the v3.0 dropdown, top-left. This is more of a placeholder ATM, but the DB model has been built to allow the documentation to be versioned and so eventually this will let you switch to a different version.

This one shows you what the Add / Edit Page modal looks like. You will be able to specify ...

• what section a link displays under
• in what order it displays
• the URL the page is located at
• the name for the link
• the breadcrumb that gets displayed
• and if the page is visible or not

This last setting will allow you to build up documentation over a period of time without having to make it live until it is ready to be published.

This last screenshot shows you what the content will look like when you are editing it in the WYSIWYG editor. This too is still a work in progress. The buttons you see in the editor will be expanded greatly, from what you see there. I only got this working recently, and so I haven't customized the editor as I would like yet. Anyway, the idea is, there will be a small Edit button beside each content section on the page. You can click the button, and it will load the content into the editor and allow you to edit all the text / images / etc in-place.

I also plan to add two tabs under the editor, one for Saved Drafts and one for History. When you edit the content for a section you will have the option to save a draft, instead of making the changes live right away. When you do, it will get saved to the Saved Drafts tab, and you can then load it up at a later date, to finish what you were working on. When you do decide to publish, the content will overwrite what is currently live and the old version will get added to the History tab. This way, if something got published incorreclty, you can go to the history tab and revert to a previous verison. I would also like to add a feature that allows you to do a DIFF between two selected versions too.

So that about covers where I'm at. The adding / editing / removing / moving of pages is all fully working right now, but the content section stuff and the WYSIWYG editor is still a work in progress. Once that is done, I will commit the code and you will be able to demo it at that URL I used last time, and provide feedback for improvements. After that, I will start committing more incrementally.

Also, after the demo goes up, I will start working on the next phase, which includes ...

• figuring out how we should link to the archived documentation
• adding user authentication so only people with access can make documentation changes
• optimizing everything for mobile (it should work fairly well on ipad / tablet landscape out of the box, but it will need lots of tweaking to make it usable on smaller screen sizes like a mobile phone)
• add the ability to comment on documentation pages by integrating Discourse

Let me know what you think. Is the direction I'm going looking good, or should I rethink what I'm doing?

[gchiu]

This is looking like a mammoth effort here! If all the editing is being done in situ rather than GitHub, will there be a problem with reverting pages that get damaged by either error or a malicious user. We're had that happen on the wiki which has to be tediously reverted.

[BrianOtto]

What do you mean by tediously reverted? What did you have to do to restore the previous pages?

It would just be a button click to restore a previous version of a section (a section is a small portion of a page). I guess if someone went in and updated all the sections of a page maliciously then you would have to click the revert button on however many sections are on that page... though I was under the impression the official documentation wouldn't be open to editing by the public, like a wiki is, but by a select few individuals who would be trustworthy. I guess if you did want it more open then you could build in two types of users: ones who can create drafts only and ones who can create drafts and also approve them.

The idea behind making it editable through the website, rather than github, is it allows the documentation to be edited anywhere (i.e. on your phone, at work, etc). You don't need any special tools to edit or publish the content. It also allows you to have a real-time preview of what the updates will look like.

The effort isn't that mammoth, I build these types of things in my day job. However, it is a custom solution, so if you guys aren't comfortable with that and would rather go with something that already exists then I can look into that instead. For managing pages in Github the two main solutions out there would be Jekyll (runs on Ruby, has lots of plugins) or Hugo (runs on Go, has faster preview times than Jekyll). We'd have to pick one of those, and then I would need to convert the site layout to the internal formats they use.

[gchiu]

I don't think we had different types of users so maybe that's the way to go.

Let's see what others say.

[hostilefork]

Looks like a nice functional layout--though I definitely want the logo to be black and white! (One spin on the logo I had was that daily builds would have hazard marks, but by and large black/white/grey is the coloring to go with.)

There may be a number of pages where a content-management-system with easy editing would be good. From the experience here on this forum, I've certainly found it easier than going through a generative process, or needing to send a PR to get an update. I type fast so perhaps having a low-inertia editing mechanism would be good.

But perhaps that's a better fit for rebol.info? What we're looking at for rebol.org is less of a tutorial-and-exposition site. Much more of a modules-and-help place, just the facts. I assume you've seen help.rebol.info here at some point:

http://help.rebol.info/append

We want to be able to augment the generated help descriptions with some other information. (I've wondered if the SEE ALSO might come from the code, as well, so that you get that in the console even with no internet connection.) And we know those generated descriptions will change. Same with modules, they'll be guiding what needs to be on a help page with what's in their headers...it just might be nice to be able to add a bit more.

I think what Graham is saying is that he sees the documentation effort as being something very distributed... where the desire is to be able to easily incorporate updates from users out on the web. So workflow would be a lot more like Wikipedia than like a traditional content management system (WordPress/Joomla) where you get a login and edit in a WYSIWYG. It should be relatively easy to revert if someone goes in and does damage.

So the question is how we can drive a website for the casual reader from git repositories that change day to day. It may be hard to shoehorn that in with a traditional CMS with an editor and a MySQL database. And we want to be careful about using any custom code that isn't written in Rebol...or even that is...because people tend to disappear when they don't have free time, and we need to be sure whatever we have can live on even if the original developer isn't available.

I personally like using Trello for some things, and it might be interesting to have some set of pages whose content is dynamically generated from the state of a Trello card...if the card follows some consistent system of formatting. So things like that are a possibility, and save one the hassle of writing an editor...you just sort of have to create a URL system and a bit of code to do the processing after fetching the data from Trello.

But either way, the layout and experience needs to be decided on, run through the HTML5 validator, etc. etc. So I think maybe we should have some more forum threads just brainstorming on that. I think help.rebol.info is a good starter for thinking, but there's a lot to deal with even there...how are weird Rebol name characters translated to URLs? Would do* become help.rebol.info/do-star, for instance? Should there be a context like help.rebol.info/lib/append? Will help for modules be generated under the same index, help.rebol.info/json/serialize?

So a lot of those kinds of questions here. It's definitely good to reason about the front page experience, but we probably aren't aiming to have a whole lot of essays beyond that. So maybe what you're thinking about with a content management system is a better fit for rebol.info, where bloggy-style announcements might be done. (maybe linking to comments here on the forum, the way Jeff Atwood's blog does for commenting.)

But continue experimenting, and maybe just spawn new topic threads here when you're thinking about something and want feedback...!

[BlackATTR]

I think you're doing a great job. This is definitely a huge leap forward, in my opinion. Thanks for all that hard work Brian!

[gchiu]

A few things

1. I'd rather the user authentication system be handled by someone else eg. github
2. Github allows discussion on PRs, but unless you've got a wiki setup with discussion pages, you won't be easily able to tell someone why you reverted their changes.
3. Being in a repo means someone can make an offsite copy

Maybe we need super users who can edit in situ, but everyone else has to do a PR? Which is sort of what Carl had, except he never approved any fixes!

[BrianOtto]

Ok, np, will switch gears and look into a Github solution. I'll also see if there is something we could do outside of the Jekyll / Hugo frameworks, maybe something more light weight, where it is just a URL system that fetches the content from Trello, the Github MD files or some such source like @hostilefork was mentioning.