SilverStripe docs - how where what?

206 views
Skip to first unread message

Martimiz

unread,
Oct 30, 2012, 12:04:30 PM10/30/12
to silverst...@googlegroups.com
Hi guys

I've been looking into the structure of the docs again - trying to decide where to put my contributions - and I'm not quite sure if I really understand the concept or how this is going to develop once the amount of documentation grows…

There are (only) seven main categories (no subcategories), and it isn't always clear what should go where, so there is an amount of overlap already.

Also the introductionpage for each category needs to be updated manually each time a new item is added/changed/removed This is hard to maintain, so left menu and introduction are not aligned.

3. From the main categories 'Changelogs', 'Installation' and 'Tutorials' are obvious, and I can see that 'Howto' should probably contain snippets and recipes, but the rest seem somewhat fuzzy.

Misc:
Everything that doesn't belong in one of the others? At this point mainly developer directives (how would you call those?)

Reference:
"Reference articles complement our auto-generated API docs in providing deeper introduction into a specific API."

Topics
"This section provides an overview on how things fit together, the "conceptual glue" between APIs and features..."

I'm not sure I grasp the difference between Reference and Topics from these descriptions. Judging from their contents it looks a bit arbitrary already: FormFields in Reference and Forms in Topics,  GridField in Topics and ComplexTableField (should it even be there) in Reference. Also the module release process is in Misc, while other Modules stuff is in Topics, and more...

As most items seem to go either in Reference or in Topics, I foresee very long lists of items, alphabetically sorted instead of by subject, that are hard to search. Of course other categories can be added when things get out of hand, but maybe it's a good idea to (re)arrange beforehand? Or at least create clear instructions on where things should go?

I'm absolutely willing to help out with this, just let me know.

Martine

Ingo Schommer

unread,
Oct 30, 2012, 2:09:35 PM10/30/12
to silverst...@googlegroups.com
Hello Martine,

On 30/10/2012, at 5:04 PM, Martimiz <mart...@gmail.com> wrote:


I've been looking into the structure of the docs again - trying to decide where to put my contributions - and I'm not quite sure if I really understand the concept or how this is going to develop once the amount of documentation grows…


There are (only) seven main categories (no subcategories), and it isn't always clear what should go where, so there is an amount of overlap already.
The different categories are explained in "what to write".
Topics should be the natural extension after reading the tutorials,
in a less linear style, but still providing a high level picture.
This contrasts reference, which can deal with a single class.
For example, you'd have a topic called "Scaffolding",
which mentions ModelAdmin, GridField, searchable fields, etc.
Then you'd have a reference article for ModelAdmin itself,
with more detail on configuration options.

In general, do you agree that there's value with providing
a collection of higher level documents other than the tutorial,
which are separated from more low level docs like howtos and class details?

To illustrate my point, compare Symfony's "books" (=topics) and "reference":


Also the introductionpage for each category needs to be updated manually each time a new item is added/changed/removed This is hard to maintain, so left menu and introduction are not aligned.
That's an architectural decision we've made when developing the docsviewer module
which drives doc.ss.org. An automated listing means we can't reorder, group or edit
links to the contained documents and subdirectories. I agree that its a pain to maintain,
but a necessary tradeoff IMHO. 

In the end, both the docsviewer module and doc.ss.org codebase are opensource,
and we're happy for any contributions to make them better:

Its a bit of a pain to maintain our own toolset for this,
but that's the direction we decided on. Frankly, if I could go back
and change it, we'd probably have a RestructuredText and Sphinx
powered documentation now, which takes care of a lot of basic stuff
like customizeable document listings.


3. From the main categories 'Changelogs', 'Installation' and 'Tutorials' are obvious, and I can see that 'Howto' should probably contain snippets and recipes, but the rest seem somewhat fuzzy.

Misc:
Everything that doesn't belong in one of the others? At this point mainly developer directives (how would you call those?)

Reference:
"Reference articles complement our auto-generated API docs in providing deeper introduction into a specific API."

Topics
"This section provides an overview on how things fit together, the "conceptual glue" between APIs and features..."

I'm not sure I grasp the difference between Reference and Topics from these descriptions. Judging from their contents it looks a bit arbitrary already: FormFields in Reference and Forms in Topics,  GridField in Topics and ComplexTableField (should it even be there) in Reference. Also the module release process is in Misc, while other Modules stuff is in Topics, and more…
Agreed, GridField and CTF shouldn't be in there, I've moved them (in 3.0, needs merge to master).
"Forms" is a topic, so an introduction to the field of interest,
while "Form Fields" is just a list of fields in a more lookup style.

As most items seem to go either in Reference or in Topics, I foresee very long lists of items, alphabetically sorted instead of by subject, that are hard to search. Of course other categories can be added when things get out of hand, but maybe it's a good idea to (re)arrange beforehand? Or at least create clear instructions on where things should go?

I'm absolutely willing to help out with this, just let me know.
That's great news :) We could use help to consolidate and organize the existing docs.
There's lots of places to work on, here's an overview:
Feel free to choose from there (ensure to assign yourself first). If you want to work on a different larger aspect,
I would suggest that you create a ticket for it first describing your intentions, and CC me so we can discuss
and ensure its heading in the right direction.

Thanks heaps for caring about documentation!
Ingo

Martine

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/HPvLvh2UwWYJ.
To post to this group, send email to silverst...@googlegroups.com.
To unsubscribe from this group, send email to silverstripe-d...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.

Martimiz

unread,
Oct 31, 2012, 8:16:28 AM10/31/12
to silverst...@googlegroups.com

Hi IngoYes, and reread it :-)

> Topics should be the natural extension after reading the tutorials,
> in a less linear style, but still providing a high level picture.
> This contrasts reference, which can deal with a single class.

So if I understand this correctly:

- Reference should contain more verbose wrappers for single classes and their API's
- Topics should explain how certain classes collaborate to create functional entities
- Howto should provide examples of how to and where to implement/use functional entities
- Tutorials should contain articles on how to build apps (or parts thereof) in SilverStripe  

So technically, taking the gridfield as an example: we describe the various base classes and components in Reference, then in Topics show how to set up a grid field using components, then use Howto to show examples of special GridField setups or how to write a custom component and also have gridfields turn up in Tutorials as part of larger 'apps'. I take it this is what we're aiming at, though it won't always be possible to set it up exactly this way?

Or would we still place the Gridfield in Reference even though it's not single class, since all other single class FormFields are explained there and people might look for it there as well?

And, for better understanding, items like for instance Templates, Templates Formal syntax, Templates Upgrading Guide and URL Variable Tools would be moved to Topics, as the don't wrap a class or an API  so much?

 
> In general, do you agree that there's value with providing
> a collection of higher level documents other than the tutorial,
> which are separated from more low level docs like howtos and class details?

There might be room for a few more. For instance: I do think directives for contributors need a category of their own (they're mostly in Misc now anyway :)


> To illustrate my point, compare Symfony's "books" (=topics) and "reference":
> http://symfony.com/doc/master/book/index.html
> http://symfony.com/doc/current/reference/index.html

OK, take our reference/topic menus - on click they open very large submenus,  pushing other main items all the way to the bottom. Clicking an item adds another (content) menu to the top that can be quite large as well. Now if you then click an item that has sub-items, once you are at the top of the document you totally lose track of where your original item with its (important) siblings is located in the tree…

Another thing: should we allow grouping submenuitems in submenu's of their own? In that case the Theme should mark them more clearly in the list, I think…

Symphony avoids it all by showing only the top-level documents in the sidebar, placing all necessary links in the top-level documents themselves, and placing the 'in this document' underneath the main menu. Definitely less cluttered. To get back to the 'submenu' just click the main category again - no problem there.

The one issue is that now everything depends on maintaining the top-level documents, and I wonder if thats going to work in the SS docs. We could still separate the toplevel menu and the sub menu. Maybe even introduce a header menu? But still, if reference/topics grows we could look at a very large submenu indeed. In topics using submenu's could maybe help. 

> In the end, both the docsviewer module and doc.ss.org codebase are opensource

I've a version running :) I'm thinking of playing a bit with it when I have time, see if I can make some ideas visual.  I hope my reactions make some sense to you, as it's all a bit complex to fit in a simple mail :-)

Thanks, Martine




Ingo Schommer

unread,
Oct 31, 2012, 8:47:39 AM10/31/12
to silverst...@googlegroups.com
Hello Martine,
On 31/10/2012, at 1:16 PM, Martimiz <mart...@gmail.com> wrote:

So technically, taking the gridfield as an example: we describe the various base classes and components in Reference, then in Topics show how to set up a grid field using components, then use Howto to show examples of special GridField setups or how to write a custom component and also have gridfields turn up in Tutorials as part of larger 'apps'. I take it this is what we're aiming at, though it won't always be possible to set it up exactly this way?
Don't take the "reference = single class" guideline too strictly.
The main goal here is to keep the topics section highlevel.
Ideally we could reorder it a bit, and each topic would form the chapter of a book.
They don't need to be 100% coherent, but I don't think "templates formal syntax" would be
a book chapter on the same level that "controllers" and "forms" is.
A book shouldn't have a 100 chapters either, so as I said,
I'm all for consolidating topics into higher level logical units,
and leaving the rest in reference and howtos.

One thing to note: The distinction between topics and reference becomes less relevant the more
useful our search is. I don't expect many people to browse through
an index of 50+ reference pages, they'll be mostly found by searching for a term.

Or would we still place the Gridfield in Reference even though it's not single class, since all other single class FormFields are explained there and people might look for it there as well?

And, for better understanding, items like for instance Templates, Templates Formal syntax, Templates Upgrading Guide and URL Variable Tools would be moved to Topics, as the don't wrap a class or an API  so much?
"Templates" is a topic, the other ones are lowlevel reference docs.

 

Another thing: should we allow grouping submenuitems in submenu's of their own? In that case the Theme should mark them more clearly in the list, I think…
Not sure what you mean, maybe a mockup would help?


Symphony avoids it all by showing only the top-level documents in the sidebar, placing all necessary links in the top-level documents themselves, and placing the 'in this document' underneath the main menu. Definitely less cluttered. To get back to the 'submenu' just click the main category again - no problem there.
Agreed that "in this document" is not well placed in the sidebar, it should be in the main content. Want to send a pull request?


The one issue is that now everything depends on maintaining the top-level documents, and I wonder if thats going to work in the SS docs. We could still separate the toplevel menu and the sub menu. Maybe even introduce a header menu? But still, if reference/topics grows we could look at a very large submenu indeed. In topics using submenu's could maybe help. 

> In the end, both the docsviewer module and doc.ss.org codebase are opensource

I've a version running :) I'm thinking of playing a bit with it when I have time, see if I can make some ideas visual.  I hope my reactions make some sense to you, as it's all a bit complex to fit in a simple mail :-)
Awesome, first step is done then :) Cheers!

Thanks, Martine






--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/rI5GJaWGVRIJ.

Martimiz

unread,
Nov 1, 2012, 1:26:17 PM11/1/12
to silverst...@googlegroups.com

Hi Ingo,

I realize that the focus is on the framework documentation at the moment and that other modules and translations are a thing of the future.

But because some documentation for other modules has already been written, it would be nice to have it available, as it would encourage people to keep adding proper documentation.

Some developers are now using the README to document their overview and install instuctions. That means this information will never make it to the docs. Should this be addressed?

And how would the workflow for adding docs for modules and widgets be? Would you wait until a new module release platform is realized? Would you only add documentation for modules you support - or would the goal eventually be that every module and widget can be represented?

Martine

Ingo Schommer

unread,
Nov 1, 2012, 1:48:12 PM11/1/12
to silverst...@googlegroups.com
I actually think that README files work reasonably well for the vast majority of modules,
which usually don't have more than a couple of screen pages worth of docs.
Github makes them nicely presentable through Markdown.
If a module has more docs, they can choose to use the docs/ subfolder convention, a Github wiki,
or a custom hosted doc generator (like SilverCart).

I see two problems with allowing modules on doc.ss.org:
- It gets confusing what is considered the "core package" (people will ignore breadcrumbs, search filters, etc)
- We don't have a self-service web UI for registering modules, new versions etc.
So any of these actions incur admin overhead at the moment, on a server which
we can't give the community access to for infrastructure reasons.

Both of those concerns can be resolved somehow,
but I'm just not sure its worth investing the effort in the short term.

On a higher level, I think a revamped ss.org/modules will
be a much better place to point to individual module docs,
which can be written in whatever fashion the maintainer chooses.
One possible enhancement would be to display the README right there.

Ingo

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/XSc7X37mAJYJ.

Martine Bloem

unread,
Nov 1, 2012, 3:53:22 PM11/1/12
to silverst...@googlegroups.com



I actually think that README files work reasonably well for the vast majority of modules,
which usually don't have more than a couple of screen pages worth of docs.
Github makes them nicely presentable through Markdown.
If a module has more docs, they can choose to use the docs/ subfolder convention, a Github wiki,
or a custom hosted doc generator (like SilverCart).

I see two problems with allowing modules on doc.ss.org:
- It gets confusing what is considered the "core package" (people will ignore breadcrumbs, search filters, etc)
- We don't have a self-service web UI for registering modules, new versions etc.
So any of these actions incur admin overhead at the moment, on a server which
we can't give the community access to for infrastructure reasons.

I see :) 

Do you think that at least SilverStripe semi-core modules could be part of the docs eventually? Even just mentioned? For instance, Translatable has one (1) really nice page, for which you wouldn't normally create a whole section, but still...

Maybe module owners could write an introductory page on their module for the docs, including links to where the actual info (and  module, as long as there's no platform) can be found? There could be an extra toplevel page for that...

I hope you understand that I only trying to find out what the docs are supposed to be in the end, the way you guys see it. I'm absolutely not trying to push anything :)

Martine

Martimiz

unread,
Nov 2, 2012, 2:45:49 PM11/2/12
to silverst...@googlegroups.com
Hi,
I've been playing with the doc.silverstripe.org module a bit - really liking the docviewer module :) - to check how things would work:

- moved the table of contents to the top of the document and made it slide down on click
- created 'back to top' links for headers
- moved the breadcrumbs more to the top of the content
- split the submenu into two sidebar blocks (main items and children) 

This is mostly quick and dirty jQuery,very few template/css changes and not very fancy at all. I sort of like the breadcrumbs in that position (I find mysel fusing them more) and the TOC this way, but I am not sure about the split-up sidemenu. I would very much like to hear your opinion, just tell me if you think I'm on the wrong track!

Find it here: http://lab.balbus.tk/

As to the sub-submenus mentioned earlier: take Topics | Testing: it is very deep at the bottom of the list and clicking it removes the menu item out of sight before you even see that it has children...

Martine

Ingo Schommer

unread,
Nov 2, 2012, 2:59:39 PM11/2/12
to silverst...@googlegroups.com
Hey Martine,

On 2/11/2012, at 7:45 PM, Martimiz <mart...@gmail.com> wrote:

> Hi,
> I've been playing with the doc.silverstripe.org module a bit - really liking the docviewer module :) - to check how things would work:
Pre-hackfest hackfest, that's awesome! :)
>
> - moved the table of contents to the top of the document and made it slide down on click
Looks good! Maybe less padding between the elements?
And just call it what it is: "Table of Contents".
The arrow is too large and saturated, the "back to top" one would fit better I think.
But that's really minor. "Click to open" is noise, that's what cursor states are for.

> - created 'back to top' links for headers
I find them a bit to visually intrusive. They're too saturated, but mainly they just break the text left alignment.
Is this really an important feature? Have people forgotten how to scroll? ;)
I never use these kinds of links...
> - moved the breadcrumbs more to the top of the content
Can you make them a larger font, and move them to the right
on the same alignment as the actual content? That should make
the relationship a bit clearer - at the moment they're basically overlooked.
> - split the submenu into two sidebar blocks (main items and children)
That breaks the hierarchical relationship a bit, which is an important indicator for users.
But I see your point about the list getting too long.
Maybe we keep them as a nested list, but make it expandable, and collapse it by default?

In general, its probably more efficient to wireframe things first.
We don't have to review and discuss every little change,
but for larger bits like the side menu split it makes sense.

Thanks so much for getting this started!
Are you gonna be around at the Hackfest starting in 2h?

Ingo

Martine Bloem

unread,
Nov 2, 2012, 4:16:18 PM11/2/12
to silverst...@googlegroups.com
Hi Ingo, thanks, you're really fast :)

I know, the layout and texting aren't up to standards in any way and I agree on the use of wireframing. In this case I just wanted to see how these changes would affect working with the long menulists and if it would be interesting to explore this further. I don't consider myself a true designer anyway :)

>> Are you gonna be around at the Hackfest starting in 2h?

Eh.. In Wellington? It has already been a long day.. ;) Have a great fest!

Martine

Martimiz

unread,
Nov 6, 2012, 6:50:08 AM11/6/12
to silverst...@googlegroups.com
Hi Ingo, everybody

still on lab.balbus.tk:

- moved the breadcrumbs to the top of the content
- removed the 'back to top links'
- changed the appearance of the TOC
- relocated the TOC s it is now underneath the page title - if there is one.
- kept the mainmenu and the submenu seprated for now.

This is till only a suggestion, very basic. I'm still not sure about the sidemenu - but using very long nested submenus doesn't work very well. Using Javascript to 'up-down' could be an option, but that would mean that the content of every subfolder needs to be parsed on every request. Are these data cached?

 This is as far as I'll go for now :-) next step would probably be wireframing, as you suggest. Interested what others think as well :-)

One other question concerning docs:
There is a request on open. for the checking of links and stuff in the docs. How would that work - would one single branche on GitHub do? It would probably involve lots of minor changes and commits.

Should this request also include removing/replacing outdated links, like video's that show how to do things in version 2.2 and 2.3 :) ? Do we need more video's, is there an inventory of what is available on the web already?

Martine

Ingo Schommer

unread,
Nov 6, 2012, 7:07:32 AM11/6/12
to silverst...@googlegroups.com
Hello!

On 6/11/2012, at 12:50 PM, Martimiz <mart...@gmail.com> wrote:

Hi Ingo, everybody

still on lab.balbus.tk:

- moved the breadcrumbs to the top of the content
- removed the 'back to top links'
- changed the appearance of the TOC
Could you make both the collapsed and expanded views
a bit more space efficient (= less padding)? The collapsed
view also needs its title vertically aligned, and I would prefer
if we keep the text left, and put the arrow after the title.

- relocated the TOC s it is now underneath the page title - if there is one.
- kept the mainmenu and the submenu seprated for now.
All good changes, thanks!


This is till only a suggestion, very basic. I'm still not sure about the sidemenu - but using very long nested submenus doesn't work very well. Using Javascript to 'up-down' could be an option, but that would mean that the content of every subfolder needs to be parsed on every request. Are these data cached?
Hm, true - we could do partial caching in SS templates,
either based on recursive file modification time checks,
or by looking at the current git sha (more coupling, but easier).

 This is as far as I'll go for now :-) next step would probably be wireframing, as you suggest. Interested what others think as well :-)
Great! Want to submit a pull request?


One other question concerning docs:
There is a request on open. for the checking of links and stuff in the docs. How would that work - would one single branche on GitHub do? It would probably involve lots of minor changes and commits.
Which ticket are you referring to? For a general cleanup, one branch should be fine.
Just create separate branches for bigger pieces of work, e.g. rewriting a tutorial.


Should this request also include removing/replacing outdated links, like video's that show how to do things in version 2.2 and 2.3 :) ? Do we need more video's, is there an inventory of what is available on the web already?
I've never been a fan of SS docs screencasts, at least for the official docs, precisely because they date so quickly,
and are so hard to update. So my vote goes to removing them, rather than planning to add more.

Martine

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/8dph9p4Zfx0J.

Martimiz

unread,
Nov 6, 2012, 8:55:41 AM11/6/12
to silverst...@googlegroups.com
And hi again,

Could you make both the collapsed and expanded views
a bit more space efficient (= less padding)? The collapsed
view also needs its title vertically aligned, and I would prefer
if we keep the text left, and put the arrow after the title.

OK: made it less padded and moved the arrow. Not sure what you mean by aligning the title though: aligning it to the left with the rest of the content text? It would mean removing the blue box around it, and I kind of like that...
 
Great! Want to submit a pull request?

I can do that - as long as it's clear it really is only meant as kind of a raw mock-up.
 

Which ticket are you referring to? For a general cleanup, one branch should be fine.
Just create separate branches for bigger pieces of work, e.g. rewriting a tutorial.

I must have misread something, since I cannot find it anymore. Would it be a good idea to create one?

- remove links that are no longer valid for the current version especially in index.md files)
- rebuild links that point to older versions of things
- add API links where missing (at the bottom of documents)
- add new useful links to overview pages
- ???
 
Martine

Ingo Schommer

unread,
Nov 6, 2012, 9:00:07 AM11/6/12
to silverst...@googlegroups.com
Hey Martine,
On 6/11/2012, at 2:55 PM, Martimiz <mart...@gmail.com> wrote:

And hi again,

Could you make both the collapsed and expanded views
a bit more space efficient (= less padding)? The collapsed
view also needs its title vertically aligned, and I would prefer
if we keep the text left, and put the arrow after the title.

OK: made it less padded and moved the arrow. Not sure what you mean by aligning the title though: aligning it to the left with the rest of the content text? It would mean removing the blue box around it, and I kind of like that...
You've fixed the _vertical_ alignment of the text, all good (so equal space between the text and top/bottom of the box).
 
Great! Want to submit a pull request?

I can do that - as long as it's clear it really is only meant as kind of a raw mock-up.
The whole doc.ss.org was more or less a raw mock-up,
its the only way things like these have a chance of going live
with the limited time we have for them :) So its great to see
somebody like you chipping in!

 

Which ticket are you referring to? For a general cleanup, one branch should be fine.
Just create separate branches for bigger pieces of work, e.g. rewriting a tutorial.

I must have misread something, since I cannot find it anymore. Would it be a good idea to create one?
I'd say just go ahead and fix the smaller stuff, its unlikely that somebody else will take it up in the meantime.

- remove links that are no longer valid for the current version especially in index.md files)
- rebuild links that point to older versions of things
- add API links where missing (at the bottom of documents)
- add new useful links to overview pages
- ???
 
Martine


--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/DGPiLzs5accJ.

Martimiz

unread,
Nov 7, 2012, 10:36:10 AM11/7/12
to silverst...@googlegroups.com
Hi Ingo

 
The whole doc.ss.org was more or less a raw mock-up,
its the only way things like these have a chance of going live
with the limited time we have for them :)
 
Before I go sending pull requests: (almost) all changes I made are in the docsviewer module, not in the doc.silverstripe.org app. And there is no way I can move everything to doc.silverstripe.org... :( But as others might use the docsviewer module as well, would changes like this even be acceptable? Or should maybe a new ss-branch in the original docsviewer be created first?

Martine

Ingo Schommer

unread,
Nov 7, 2012, 10:47:24 AM11/7/12
to silverst...@googlegroups.com
At the moment docsviewer and doc.ss.org are fairly synonymous in terms of design, so that's fine with me.
Once we see docsviewer being used with other designs on other websites, we have to be a bit more
careful about adding features to the default template, and moving stuff around, but for now we're golden.

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/p4EMLwNvrfwJ.

Sam Minnée

unread,
Nov 7, 2012, 1:48:29 PM11/7/12
to silverst...@googlegroups.com
To be honest I'd prefer to go the other way and have docsviewer implement the design of doc.ss.org much more closely. In particular, it gets annoying to write docs previewing at once template width, and then deploy them to doc.ss.org at another width.

IMO the special code in doc.silverstripe.org should be limited only to stuff that says "this is the SilverStripe documentation site". Not much value in maintaining 2 separate-but-similar designs.
-------
Sam Minnée | Chief Executive Officer
SilverStripe
http://silverstripe.com

Phone: +64 4 978 7334
Skype: sam.minnee

Martimiz

unread,
Nov 8, 2012, 8:55:07 AM11/8/12
to silverst...@googlegroups.com

As this was only meant to be a mock-up, I've not cared about nice topic-by-topic commits. This may be a bit much for one single commit? If not I can push this for a pull request. Otherwise I'd have to do a step by step rebuild. I've got things logged, so I could, although it's a bit of work :)

Btw: I've added arrows to submenu items that have children, and also fixed an issue where breadcrumbs for the stable version still had the version a part of the url, where the menu's haven't (double content). This is the version now on lab.balbus.tk


To be honest I'd prefer to go the other way and have docsviewer implement the design of doc.ss.org much more closely.  In particular, it gets annoying to write docs previewing at once template width, and then deploy them to doc.ss.org at another width.

IMO the special code in doc.silverstripe.org should be limited only to stuff that says "this is the SilverStripe documentation site".  Not much value in maintaining 2 separate-but-similar designs.


At a glance that would mean first moving all styles referring to the docsviewer module from themes/ssorgsite/css to docsviewer/css, as well as all of the images except the ones referring to the ss toolbar. Also themes/docs should be transferred: javascript (jQuery) should go live in doscviewer and the templates in themes/ssorgsites. Also docsviewer would need its own routing. Do you think that that's about it?

For me, I would like to be able to run docsviewer from a default SS3 install, without the need for app. It would be great to write custom user documentation for complex websites :-) Unfortunately I can't get that to work yet, because the current routing seems to overwrite cms routing, and I know too little about routing - I could use some help there :)

Anyway: I would like to not use app, but use mysite instead, just like with 'ordinary modules'. That would also allow me to overwrite settings/templates, which doesn't seem to work very well with app or themes...

Martine

Martimiz

unread,
Nov 8, 2012, 9:00:45 AM11/8/12
to silverst...@googlegroups.com
By the way: I haven't been able to get search to work, it always results in a 404. Is that because lucene isn't properly installed, do you think? It feels like something else, but I haven't a clue yet (never used lucene before)...

Ingo Schommer

unread,
Nov 8, 2012, 9:19:38 AM11/8/12
to silverst...@googlegroups.com
Hey Martine,

On 8/11/2012, at 2:55 PM, Martimiz <mart...@gmail.com> wrote:


As this was only meant to be a mock-up, I've not cared about nice topic-by-topic commits. This may be a bit much for one single commit? If not I can push this for a pull request. Otherwise I'd have to do a step by step rebuild. I've got things logged, so I could, although it's a bit of work :)
A single commit is fine for now - but it will help to familiarize yourself with "git rebase --interactive" for future contributions.

Btw: I've added arrows to submenu items that have children, and also fixed an issue where breadcrumbs for the stable version still had the version a part of the url, where the menu's haven't (double content). This is the version now on lab.balbus.tk

To be honest I'd prefer to go the other way and have docsviewer implement the design of doc.ss.org much more closely.  In particular, it gets annoying to write docs previewing at once template width, and then deploy them to doc.ss.org at another width.

IMO the special code in doc.silverstripe.org should be limited only to stuff that says "this is the SilverStripe documentation site".  Not much value in maintaining 2 separate-but-similar designs.


At a glance that would mean first moving all styles referring to the docsviewer module from themes/ssorgsite/css to docsviewer/css, as well as all of the images except the ones referring to the ss toolbar. Also themes/docs should be transferred: javascript (jQuery) should go live in doscviewer and the templates in themes/ssorgsites. Also docsviewer would need its own routing. Do you think that that's about it?
The original idea for the "ssorgsites" CSS was to share it between our different properties, for example open.ss.org, doc.ss.org, api.ss.org, etc.
In practice, that's limited to the top global toolbar (which is loaded from a central place), plus some basic link styles etc.
It turned out to be difficult to handle both code management and deployment of shared styles between those quite different platforms.

So in general I agree with Sam, it doesn't make sense to maintain two slightly different styles,
and I'm in favour of moving much of the current doc.ss.org look "up" into the docsviewer module.
But that's a secondary task, I'm more interested in getting your work live. You're welcome
to help with that styling/template migration as well of course.


For me, I would like to be able to run docsviewer from a default SS3 install, without the need for app. It would be great to write custom user documentation for complex websites :-) Unfortunately I can't get that to work yet, because the current routing seems to overwrite cms routing, and I know too little about routing - I could use some help there :)
That's the general idea, so the fact that docsviewer routing prevents you from accessing the CMS etc is a bug.
Do you want to file it on github in silverstirpe-docsviewer?

Thanks
Ingo

Martimiz

unread,
Nov 8, 2012, 12:17:48 PM11/8/12
to silverst...@googlegroups.com
Pull request sent for the docviewer.

You should probably change te following files in your doc.silverstripe.org installation, if they are set to override the ones in docviewer. I can't check this now - http://doc.silverstripe.org/ seems to be offline? Setting this right will be part of the next step.

 /themes/docs/templates/DocumentationViewer.ss (copy contents of #search-bar only)
 /themes/docs/templates/Layout/DocumentationViewer.ss (as follows)

<div id="documentation-page">
    <% if VersionWarning %>
        <% include DocumentationVersion_warning %>
    <% end_if %>

    <div id="content-column">
        <% if Breadcrumbs %>
            <% include DocBreadcrumbs %>
        <% end_if %>
        $Content

        <% if EditLink %>
            <div id="edit-link">
                <p><a target="_blank" href="$EditLink">Edit this page</a></p>
            </div>
        <% end_if %>

        <% include Comments %>
    </div>

    <% if Content %>
    <div id="sidebar-column">
        <% include DocInThisModule %>
    </div>
    <% end_if %>
</div>


Cheers, Martine

Sam Minnée

unread,
Nov 8, 2012, 3:53:21 PM11/8/12
to silverst...@googlegroups.com
You should probably change te following files in your doc.silverstripe.org installation, if they are set to override the ones in docviewer. I can't check this now - http://doc.silverstripe.org/ seems to be offline? Setting this right will be part of the next step.

Martine - would you be able to make a relevant pull request to https://github.com/silverstripe/doc.silverstripe.org ?

Martimiz

unread,
Nov 9, 2012, 6:49:19 AM11/9/12
to silverst...@googlegroups.com

Martine - would you be able to make a relevant pull request to https://github.com/silverstripe/doc.silverstripe.org ?


Sure, once the changes in docsviewer are final (to keep things in sync)

Martine 

Martimiz

unread,
Nov 11, 2012, 7:21:24 AM11/11/12
to silverst...@googlegroups.com
So I'm thinking: it is in fact very easy now to install the docsviewer module as an ordinary module in any silverStripe installation. It would then automatically register every installed module or widget giving access to all the documentations. I'never really realized that before :)

But most developers seem to use only the readme.md for documentation. Someone in this thread (Ingo?) said that that was ok, and maybe it is... If we could
make the docsviewer include the readme - and still encourage developers to use the docs directory to write their extended documentation, use the readme mostly for installatin, a short description and pointing to the docs, unless they are small modules needing almost no documentation. Any thoughts?

Martine

Sam Minnée

unread,
Nov 11, 2012, 3:15:56 PM11/11/12
to silverst...@googlegroups.com

> But most developers seem to use only the readme.md for documentation. Someone in this thread (Ingo?) said that that was ok, and maybe it is... If we could
> make the docsviewer include the readme - and still encourage developers to use the docs directory to write their extended documentation, use the readme mostly for installatin, a short description and pointing to the docs, unless they are small modules needing almost no documentation. Any thoughts?

Yes, I think this makes a lot of sense. In particular, a README.md file in the root of a project folder is both a de facto standard and something encouraged by GitHub. If we're not do this, we're putting ourselves in conflict with GitHub, which doesn't make a lot of sense.

The slightly trickier question is how to ensure that the README and the docs mesh together nicely.

How about this?

1. In any given language, if README exists and index doesn't, show the README content on the default page
2. If both README and index exist, then show index, and list README on the navigation as if it were stored at docs/en/README.md
3. If /docs/en/index.md doesn't exist but /docs/en/README.md does, then use README as an alternative to index.
4. If both /README.md and /docs/en/README.md exist, then ignore /README.md.

#4 may seem a little strange: my motivation is
- Specify behaviour of an edge case that we should advise against, without needing to monkey with the documentation IA more than is necessary.
- Allow for the creation of language-specific READMEs.

Sam Minnée

unread,
Nov 11, 2012, 5:59:51 PM11/11/12
to silverst...@googlegroups.com
Hi,

Just a note that I've updated doc.silverstripe.org this morning.

Martimiz

unread,
Nov 12, 2012, 10:36:38 AM11/12/12
to silverst...@googlegroups.com
Hi,

Just sent another pull request that generates the submenu from template instead of by javascript, as on some pages the javascript (that was only really meant for the mock-up)  kicks in a bit late and it doesn't look nice. I hope this solution will qualify, as it was a bit complex. See what Will has to say :-)

Martine

Martine Bloem

unread,
Nov 15, 2012, 10:47:44 AM11/15/12
to silverst...@googlegroups.com
Hi,
In htaccess, the entire misc directory in the docs is redirected to trunk, with the following explanation:

Anything in sapphire/en/<version>/misc is redirected to trunk, the info in there is usually not version specific and only updated on master (e g. contributon and coding guidelines)

Once redirected, you get to stay in the trunk-realm, which is somewhat confusing. I found myself several times trying to get back to 3.0, somtimes with, and sometimes (still in misc) without success. Can't we just update 3.0 on the rare occasions these files get changed?

And should misc be renamed, maybe to 'developer guidelines', or something similar that real English-speaking people can come up with :), if that's what it's meant for?

Martine


Martimiz

unread,
Dec 21, 2012, 3:34:07 PM12/21/12
to silverst...@googlegroups.com
Hi,

 
How about this?

 1. In any given language, if README exists and index doesn't, show the README content on the default page
 2. If both README and index exist, then show index, and list README on the navigation as if it were stored at docs/en/README.md
 3. If /docs/en/index.md doesn't exist but /docs/en/README.md does, then use README as an alternative to index.
 4. If both /README.md and /docs/en/README.md exist, then ignore /README.md.


I've  set up a demo for this at http://lab.balbus.tk/dev/docs/. Tell me what you think - there are 4 demo 'modules':

1. indexonly: it has /docs/en/index.md and nothing else
2. readmeonly it has a single README.md file in the root
3. readmelocalized: it has a README.md file in the root and a second localized one in docs/en. No index file
4. readmeplusindex: has a README.md file in the root and an index.md and one other page in docs/en

I've set this up for automatic registration, although it is possible to add the path to a readme-file on custom registration.

It's a bit complex because of the module enforcing at least one 'en' language directory for each documentation entity, so you cannot just register any directory. So for now I've based this on exceptions for README.md files only and passing the absolute path to the readme file on registration. It involves quite a bit of rewriting and I'd like your advice on this:

Usually I'd go for a more generalized approach - but I'm not sure where to stop here. Would we have to support README files for all supported extensions, in upper/lower case combi's? Other .md files in the root? Flexibility adds complexity. Or should we just leave it at supporting the README.md file in the root for default type modules, and assume that people writing more custom documentation systems know the 'rules'?

Martine

Ingo Schommer

unread,
Jan 2, 2013, 8:02:28 AM1/2/13
to silverst...@googlegroups.com
Hello Martine, sorry for the late reply, hope you had a nice christmas :)
I agree with the suggested behaviour, its the way of "least surprises" for docs developers.
And paste the registration code required for your sample modules (maybe a zip?).
I think the file name checks should be case insensitive, but we can assume its
called "readme.md" in terms of file name and extension. Support for parsing
other file formats is not really on the agenda at the moment, and given
that most modules barely need more than a single README file,
I don't think we'll have problems with more complex setups anytime soon
in terms of the required flexibility.

BTW, SilverStripe offices are still closed until next Monday (=reduced feedback).

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/U_zMU49cpiQJ.

Martimiz

unread,
Jan 6, 2013, 10:22:03 AM1/6/13
to silverst...@googlegroups.com
Hi Ingo,
No problem :) Wishing you guys all the best for 2013!

>> Could you push your current progress? I guess to
>> https://github.com/Martimiz/silverstripe-docsviewer/tree/readmesupport-20121219?

Now that I know where we're going on this, I'd first like to tidy up the code before sending a pull...

>> And paste the registration code required for your sample modules (maybe a zip?).

I intend to leave the registration interface as it is now. At the moment I'm using an optional parameter on registration to enter the readme path, but I'm thinking of ways to get rid of it and basically only support readme in docs that confirm to the ss module standard (entity/docs/language/)

Martine

Martimiz

unread,
Jan 7, 2013, 2:32:15 PM1/7/13
to silverst...@googlegroups.com
 Hi,

I've sent a pull request for a series of issues concerning Document Search. It broke on modules/entities that were loaded using automatic registration, and on the Document homepage it never yielded any results.

I also provided a way to optionally disable the advanced search (enabled by default): In situations where multiple modules/entities have different versions, the list of versions allows for invalid entity/version combinations, which can be very confusing.

Since these were basically bugs, I felt it more important to fix this first. Readme's next.

One other little thing would be to remove the TOC if it's empty.

The final job would be to enable setting a custom order to the menu, using 'metadata' or key/value pairs in the documents, as mentioned by Will in the DocumentViewer issues on GitHub. MultiMarkdown has support for this, but I don't think I'm up to rebuilding docviewer around that, and you'd probably be against that :) I've been playing around with some custom code, and got it working - the only thing missing is a real good proper regexp that will read the key/value pairs up to a certain point. I would like them to be just plain tekst, followed by whitespace. Something like:

order: 213
title: My New Title

Any help on that and other suggestions are welcome. Please let me know what you think.

Martine
Reply all
Reply to author
Forward
0 new messages