New Community Documentation Website5 users found helpful
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 concrete5.org 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!
Now, who do I blame for this typo that I can't edit. ^_^ (see attached)
And sadly, that'd be me.
UPDATE: and fixed
I may have be doing something wrong. But I cannot seem to log-in.
I've set to attached my account from concrete5.org, 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!
If so, do things work better in Chrome?
How do we get to the old 5.6 docs and howtos from concrete5.org?
I've been trying using Chrome.
I've just tried for the 3rd or 4th time.
I'm now logged in.
But have you changed anything? If not, it's related to server connection between docs and main .org site? Strange.
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?
Massively unhelpful. Years worth of typos/corrections are lost...
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.
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.
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.
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.).
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.