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…Agreed, GridField and CTF shouldn't be in there, I've moved them (in 3.0, needs merge to master).
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--
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.
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?
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
--
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.
--
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.
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 whichwe can't give the community access to for infrastructure reasons.
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--
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.
Could you make both the collapsed and expanded viewsa bit more space efficient (= less padding)? The collapsedview also needs its title vertically aligned, and I would preferif we keep the text left, and put the arrow after the title.
Great! Want to submit a pull request?
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.
And hi again,Could you make both the collapsed and expanded viewsa bit more space efficient (= less padding)? The collapsedview also needs its title vertically aligned, and I would preferif 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?
Martine
- 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
- ???
--
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.
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 livewith the limited time we have for them :)
--
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.
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.
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.tkTo 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 :)
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 ?
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
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.
--
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.