New Community Documentation Website

Permalink 5 users found helpful
Just wanted to let everyone know we've launched a completely new documentation website for 5.7. It includes tutorials, editor documentation, developer documentation and an updated API.

We're still working out some of the kinks, and we have of old links to redirect to the new site, but it's available and up and running. Some of the benefits of the new site include:

* Built on concrete5 5.7
* Community Powered – anyone can sign in using their username and password and edit editor documentation, developer documentation and tutorials
* Easily submit new editor and developer documentation, as well as tutorials
* Tutorials offer the ability to specify which questions a particular tutorial answers, and then search by those questions.
* All documentation pages feature conversation blocks added to them, with the ability to monitor conversations via email.
* New API doc appearance, and the ability to download the API as a ZIP file
* Code snippets are automatically syntax highlighted
* Editor documentation uses WYSIWYG editing; developer documentation uses a completely new markdown editor, with support for drag-and-drop image uploading.
* All submissions hook into concrete5 workflows, so we can quickly vet and approve documentation.

Let us know what you think!

View Replies:
wagdi replied on at Permalink Reply 1 Attachment
Wow… this is great! Can't praise you guys enough! This really is what we've been waiting for. I won't get into it too much now but I can tell you that I'm getting excited about Concrete5 again. The list of praise is huge but just to mention one… having the ability to edit and add to the docs is brilliant. :)

Now, who do I blame for this typo that I can't edit. ^_^ (see attached)
andrew replied on at Permalink Reply
Thanks wagdi, that's great to hear.

And sadly, that'd be me.

UPDATE: and fixed
katz515 replied on at Permalink Reply

I may have be doing something wrong. But I cannot seem to log-in.

I've set to attached my account from, then tried to log-in.
But I won't really be able to log-in.

Just a FYI.

But great work! Thank you for your effort!
andrew replied on at Permalink Reply
By any chance are you trying to use Safari? And does it seem to login for a second, and then logs you back out? If so, I've been having a similar issue occasionally in Safari. If not, it might be something new. Does this sound familiar or is something different happening?

If so, do things work better in Chrome?
JohntheFish replied on at Permalink Reply
Well done on the new documentation site for 5.7.

How do we get to the old 5.6 docs and howtos from
andrew replied on at Permalink Reply
On the homepage of the developer and editor documentation in the new site there should be links to the old site. The tutorials home page was missing a link but I have added it back – it's an additional tab in the tutorials list interface.
katz515 replied on at Permalink Reply

I've been trying using Chrome.

I've just tried for the 3rd or 4th time.
I'm now logged in.

It worked!


But have you changed anything? If not, it's related to server connection between docs and main .org site? Strange.
fabianvogler replied on at Permalink Reply
Great site! Like the idea of users being able to submit changes.

One thing I noticed though: On some pages not all content can be edited - my guess would be because there are multiple blocks and only the body block is available for editing?

andrew replied on at Permalink Reply
Thanks – yes, as part of the migration we had to migrate all pages with multiple main area blocks into a single content block. I thought we'd caught all these but we missed that one. It should be fixed now.
MrKDilkington replied on at Permalink Reply
Thank you, this will be a great tool for allowing the community to contribute to documentation.
ideasponge replied on at Permalink Reply
Amazing execution on this new site. Excellent job. I think this might be cutting the final tether on c5.
thirtythree replied on at Permalink Reply
Not to sound ungrateful - but why oh why did you delete all the user contributed notes and comments from the 5.6 docs?

Massively unhelpful. Years worth of typos/corrections are lost...
katz515 replied on at Permalink Reply

New documentation site has a bit short session period.

I would like to have a bit longer session time.
Just now, I happened to spend 6 hours to submit the tutorial correction (after some coffee break and job interruption)

When I finally click submit, I was logged out, and didn't get to submit the updated version.

Luckily, I saved all my changed on my Gist, I didn't lose anything.

But I am hoping if you could extend the logout expiration time a bit longer on documentation site.
Mainio replied on at Permalink Reply
I back the session length issue totally with @katz515!

I was also writing a docs page for maybe 15-20 mins and after I clicked "Submit", my session had ended which caused the doc page to disappear. The same issue also applied to the "Preview" tab under the writing view since it was displaying "Permission denied" when I tried to preview my page.

Fortunately I have worked with online forms before as well, so I also saved the changes locally before submitting the form.
JohntheFish replied on at Permalink Reply
+1. Login on the docs sites should be of similar sticky time (2 weeks) to login on
Anything that makes it less convenient to add to or edit the docs impedes the improvement of the documentation.

A few weeks ago I started updating a docs page. My session timed out. I lost the update. I din't have time or motivation to do it again. So the update never happened and I don't bother again unless I have enough additional time to mess about with local copies while I work.
Mainio replied on at Permalink Reply
I'll give some feedback after writing my first doc page (and browsing through the docs).

These are all about improving the docs site, don't get me wrong. What we currently have is better than what concrete5 has ever had before but it doesn't mean progress should be stopped at this point.

1. Creating a new doc page was not intiutive for me

I was first browsing the current docs for a good section for my docs page. I found one and I looked at the main page of that category. I was searching for a "Add new page under this section" button there but I didn't find.

After a bit more searching I found out the "Contribute" link in the top bar but it was not as obvious as the big "Edit Page" button at the sidebar of an existing documentation page.

2. Session timeout / losing changes

The session timeout time is very short (see above @katz515).

Writing good docs does not happen in a couple of minutes, it takes time. It should be expected that people are primarily using this page to write the docs.

Also, would it be good to provide some kind of caching for the comments in case the user e.g. accidentally closes the browser tab? In GitHub, I've sometimes accidentally closed the tab after writing a comment and happily noticed when I come back that my comment was still there.

This caching would not necessarily even need any server-side code, I think the web storage API could be used to implement this. E.g. after closing tab or session that ended, when going back to the docs site it would have a notification at the top of the page saying "You have yet to publish your new documentation page / documentation changes. Do you want to continue? [ Yes ]".

3. Confusing experience: Some of the top-level pages are empty

Some of the top-level category pages of the docs are empty which makes the experience somewhat confusing when browsing these pages.

I would also bring the page listing of pages under that section at the very top of each section, so that it would be easily discoverable. This would even help out with the empty page issue.

Now the empty category pages just show an empty page with the commenting section. Then at the very bottom of the page you can find out links to the sub-pages but the overall feel of this kind of pages is not great.

4. The sidebar navigation is confusing

I'm not able to clearly distinguish the separate levels on the sidebar navigation, they look so similar. This is especially for the sections that have many sub-pages where you don't necessarily see the top level page when the page is scrolled down a bit.

I see that the 3rd level pages have more intendation and different color to them but they still look very similar to the parent level (same font and same style). The difference is very slight.

Either make the 3rd level of navigation clearly in different style (like not bold and a little bit smaller font) or create some numbering system (Top level 1. Page name, Second level 1.1. Page name, etc.).
Mainio replied on at Permalink Reply
And one more:

It doesn't seem to be possible to edit some of the category pages.

For example under this page:

I don't see the "Edit Page" button.
Mainio replied on at Permalink Reply
Would be also cool if external links (to sites outside of were set to open in new tab.