User docs in markup format

[Martimiz]

For a project I have migrated the userdocs to markup format for use with the docsviewer, so if people are interested I could make them available.

Problem is, this was never a module, there is no license info and  that makes it copyright SilverStripe Ltd - and I don't want to do anything illegal :)

Any advice?

(as for preserving the right menu-order, please see this earlier post)

Martine


  

[Ingo Schommer]

Assuming you're talking about http://userhelp.silverstripe.org/, that's CC attribution licensed, so publish away :)

But we do want to ensure there's one canonical resource, to avoid them getting out of sync.

Traditionally, we had the userdocs being written by semi-technical users (like our project managers),

which is why they've been in a SS installation. They also predate our other Markdown efforts.

Now that you can edit and preview Markdown docs directly on github, I think its feasible

for these semi-technical users to work with Markdown. I need to run this by a couple of people internally though.

For now, can you publish a preview and the source somewhere so we can see where its at?

[Martimiz]

Assuming you're talking about http://userhelp.silverstripe.org/, that's CC attribution licensed, so publish away :)

Yes, I meant User help. We had talked earlier about moving it to the DocsViewer(can't recall which thread though), and it was a good test for pagesorting, keeping original URLs intact.
 

But we do want to ensure there's one canonical resource, to avoid them getting out of sync.

Understood :-)

For now, can you publish a preview and the source somewhere so we can see where its at?

Yes: http://lab.balbus.tk/dev/docs/userhelp/en

There are some very slight changes, mainly replacing some 'bold' text by header tags, to enable display in the TOC. And I hope I have the headertag hierarchy correct, but thats mostly it, I think.

[Ingo Schommer]

Looks great! Can you publish the Markdown source somewhere as well?

Can be a temporary location, will most likely move to github.com/silverstripe/userhelp-docs or something.

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Martimiz]

Looks great! Can you publish the Markdown source somewhere as well?

Can be a temporary location, will most likely move to github.com/silverstripe/userhelp-docs or something.

 
I'll create a temporary repo on GitHub

[Martimiz]

Find them here:

https://github.com/Martimiz/silverstripe-userhelpdocs/

Added some explanation as to its status, and a SilverStripe LICENCE. If this, or the repo name, is not alright, let me know.

[Ingo Schommer]

Hey Martimiz, we've got the go-ahead to migrate userhelp to Github and Markdown, yay!

I'm inclined to just copy the doc.silverstripe.org repo to the new repo I've just created.

This would create a bit of duplication (mainly templates and update.sh script),

but looks managable, particularly as the CSS is all contained in the docsviewer module both will share.

The alternative is to put userhelp onto the existing doc.ss.org site, but then

you end up with ugly URLs like doc.ss.org/userhelp-framework/3.0/managing-a-site,

as opposed to userhelp.ss.org/framework/3.0/managing-a-site. What do you think? 

Will, what's your take?

The content itself should live in another new repo. I don't want the content to live in the core modules

themselves (like we do for doc.ss.org), because it would bloat the download too much

with all the required screenshots. It also makes contributions harder because we can't

only allow contributors access to a docs folder in git, but rather the whole module.

On Saturday, February 23, 2013 4:58:53 PM UTC+1, Martimiz wrote:

[Will Rossiter]

I think a single installation separate from docs is the way to go. I'd put the content in along with the source code in this case. So we'd have a single repo "userhelp.silverstripe.org" that is basically self contained apart from docsviewer and framework dependancies. 

On Tue, May 14, 2013 at 11:12 AM, Ingo Schommer <ingo.s...@gmail.com> wrote:

bit of dupli

[Martimiz]

Hi Ingo, Will

That's great! :)

If a separate installation is the way to genererate a 'nice url', I totally agree, because the long url is plain ugly I think :)

I'm a bit confused about the need to combine docsviewer and UserHelp into one module - or did I misunderstand that bit?

One thing: at the moment the only way to to achieve the (required, I think) custom sorting of the docsviewer menu is by adding numbering to the filenames. These numbers get stripped in the menu, but they remain in the url, which I think is ugly. I kept the filenames equal to the original urls, but that didn't always work well with the menu.

So I did some work earlier on using file metatdata to adapt the menu titles, and allow for custom sorting, amongst other things, but maybe that just involves too much of a codechange for now, I could perfectly understand that :) In that case I would help with the renumbering :)

https://groups.google.com/forum/?fromgroups=#!topic/silverstripe-dev/d8jTpkQhT88

Martine

[Ingo Schommer]

Hey guys,

I've ported the repos now: https://github.com/silverstripe/userhelp.silverstripe.org and https://github.com/silverstripe/silverstripe-userhelp-content

I agree, there should be separate repos for codebase and content, otherwise versioning/branching becomes an obstacle.

Got the site running so far, but still battling with deployment a bit, will keep you posted.

For now, I've pushed it to a staging environment - can you please

check out http://test.silverstripe.com/userhelp.silverstripe.org ?

Martine, can you please remove your temporary repo? I've done a straight

copy onto our own github repo. Thanks again for getting this off the ground!

Ingo

[Martimiz]

Martine, can you please remove your temporary repo?

Done :)

[Martimiz]

 

- can you please

check out http://test.silverstripe.com/userhelp.silverstripe.org ?

It wants authentication...

[Ingo Schommer]

Ah, fixed sorry. The sort pull request slipped under my radar (https://github.com/silverstripe/silverstripe-docsviewer/pull/26/).

Will, do you have time to review it? I would prefer that over ugly number-prefixed URLs, but it also shouldn't block go-live

of the new platform. So if its something you're happy with (or can get into a mergeable state soon), that'd be awesome

[Martimiz]

- can you please

check out http://test.silverstripe.com/userhelp.silverstripe.org ?

One first thing: shouldn't 'framework' be removed from the url (the url userhelp.silverstripe.org/framework/en/) since it doesn't strictly refer to framework only?

So: userhelp.silverstripe.org/en/

[Ingo Schommer]

Sent from my iPhone

--

[Martimiz]

??? :)

[Ingo Schommer]

Suspense! ;) and #fail

Well have docs for other modules on there at some point, so it's easier to do it now then worry about redirection later. I'm not too fussed either way though if you can get it going on the root level, submit a pull request :)

[Martimiz]

It wants a name... :(

I've experimented a bit, see lab://www.balbus.tk

The idea: if you register a module as 'none' it would use an url without name. That removes the default index page as well, it would work really well if you register just one set of docs.

Obviously you'd need to check against the languages, but there a set of enabled laguages would do. Not a hughe effort. So if you want this, I can set up a pull request in a nice way :)

[Martimiz]

BTW - I'd need to know the version - 1.0 or master



Op woensdag 15 mei 2013 15:51:56 UTC+2 schreef Martimiz het volgende:

[Martine Bloem]

Stupid me - wrong old url, didn't mean to spam, sorry :(.  Meant http://lab.balbus.tk

--

[Ingo Schommer]

Hello Martine, that's looking good :) Any update on the Markdown metadata change? https://github.com/silverstripe/silverstripe-docsviewer/pull/26
I've deployed the userhelp live now with the new codebase, so fixing the ordering just got more important hehe.

BTW, search is disabled for now, it seems broken in 3.1: https://github.com/silverstripe/silverstripe-docsviewer/issues/27
Will/Martine: Could either of you look into this please?

[Martimiz]

Hi Ingo, couple of things:

So it's SS3.1?: My pull was based on ss3.0, it has been a couple of months and there have been numerous changes in docsviewer master since... :(

As for the metadata 'standard' - you want to get rid of the <!-- --> bit (other then that it looks pretty standard to me...)?  I might need some help with the regexp, the tags made it easy, without them I keep running into greedy behaviour... :(

As for the separate commits - that was on purpose: they are functional steps, not just random commits :) as this really was a major(!) overhaul and I thought Will might want to follow what I'm doing - in order to agree at all...

Busy times at the moment, I'll try and find the time.  Search... The root thing... pfff :)

Martine


Op vrijdag 17 mei 2013 11:04:23 UTC+2 schreef Ingo Schommer het volgende:

[Martimiz]

Sent a pull request for documentation in the site root for one module, multiple versions. The yaml rules I propose (see /docs/en/Configuration-Options.md) will make certain sections (like /dev) unavailable. Haven't been able to create and position the rules correctly without running into before/after conflicts :(

If anyone has a solution, besides copying existing rules, please tell me.

Martine


Op zaterdag 18 mei 2013 11:45:22 UTC+2 schreef Martimiz het volgende:

[Ingo Schommer]

Its as "standard" as things get with Markdown (which isn't very far...). At least will futureproof our documents for usage with other common Markdown parsers and extensions like MultiMarkdown.

I'm OK with leaving the commits unsquashed to get this over the line, but stand by my opinion: For 99% of pull requests, there's no reason to include merge commits, they basically

make it impossible to rebase and rewrite commits before those merges.

Simon has proposed a solution on the dev/ routing, could you see if that works for you?

Thanks for your work Martine, we're nearly there :)

Ingo

[Martine Bloem]

About the commits, I get that :) I hope I can get the entire thing 'sqhashed' into the current master easily, since there have been so many changes on both sides, including ss3.1 itself. Would it be an idea to create a new branch on github for that? I'll ry to find the time next week..

As for Simons proposal, I'll definitely try that :)  Basically anyone can - just place something like it in mysite and see what happens :). Because being able to overrule the contentcontroller from the root up without losing dev and other built-in stuff isn't in itself a docsviewer issue I think - It's more that the before and afters in cms and framework circling back and forth  make it kinda hard...

Great that things are going to work out though :)

[Martimiz]

Pull request sent. It now supports metadata with and withhout the use of comment tags. Without them, they show on the page right below the breadcrumbs, which I feel is confusing. So in that case we'd probably have to hide them again, using javascript?

Btw: this version doesn't support the README rootpages yet, I thought to first have this one done :)

I can't seem to get Simons routes.yml proposal to work. See GitHub :(

Martine


Op maandag 20 mei 2013 12:00:21 UTC+2 schreef Martimiz het volgende:

About the commits, I get that :) I hope I can get the entire thing 'sqhashed' into the current master easily, since there have been so many changes on both sides, including ss3.1 itself. Would it be an idea to create a new branch on github for that? I'll ry to find the time next week..

As for Simons proposal, I'll definitely try that :)  Basically anyone can - just place something like it in mysite and see what happens :). Because being able to overrule the contentcontroller from the root up without losing dev and other built-in stuff isn't in itself a docsviewer issue I think - It's more that the before and afters in cms and framework circling back and forth  make it kinda hard...

Great that things are going to work out though :)

To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-dev+unsubscribe@googlegroups.com.
To post to this group, send email to silverstripe-dev@googlegroups.com.