Add WMD (Stackoverflow) style editor for content authors

pmuir commented 11 years ago

having an editor which has buttons for different markdown styles will keep non-technical authors happy, as it gives them a clue as to the options and the syntax of markdown.

WMD style seems a good option, but ideally with tables support.

mojavelinux commented 11 years ago

Why Markdown and not AsciiDoc?

In general, though, I agree this is useful. You could just use the code from Gollum (the GitHub Wiki).

LightGuard commented 11 years ago

I don't see why we couldn't support AsciiDoc, Markdown and Textile. The same way Gollum does.

On Thu, Jun 20, 2013 at 5:33 PM, Dan Allen notifications@github.com wrote:

Why Markdown and not AsciiDoc.

In general, though, I agree this is useful. You could just use the code from Gollum (the GitHub Wiki).

— Reply to this email directly or view it on GitHubhttps://github.com/awestruct/web-editor/issues/12#issuecomment-19790459 .

Jason Porter http://en.gravatar.com/lightguardjp

mojavelinux commented 11 years ago

Don't allow Textile. It's dead.

As for Markdown, which one? I suppose GFM would be best.

LightGuard commented 11 years ago

Does it integrate with Tilt, or would we need to do a new tilt integration? I'd suggest Kramdown if not (or cut another quick awestruct release)

On Thu, Jun 20, 2013 at 11:16 PM, Dan Allen notifications@github.comwrote:

Don't allow Textile. It's dead.

As for Markdown, which one? I suppose GFM would be best.

— Reply to this email directly or view it on GitHubhttps://github.com/awestruct/web-editor/issues/12#issuecomment-19798632 .

Jason Porter http://en.gravatar.com/lightguardjp

pmuir commented 11 years ago

Why markdown, not asciidoc?

In particular, (for this first iteration), this editor is aimed at non-technical authors (such as marketing folks) who want to edit copy on websites built on awestruct. We can expect them to have a some knowledge of HTML, not much more. In our research, even simple guides like the kramdown syntax guide (probably no more than 5 sides of A4) was too much for them to get to grips with.

Markdown is our choice for them, as it offers a really simple syntax. I would definitely like to support Markdown Extra, as table and definition list support is important for these sorts of pages.

As a secondary goal, we want to put a facade over git/github with the tool, allowing a much simpler interaction (loosing most of the power) than enforces our workflow (create branch when they start a new session, commit on save, fixup, push, and create a pull request when the submit)

A second audience (for a later phase) is designers, who edit CSS and HTML mainly, who are comfortable with editing these techs, but perhaps aren't so happy with git and the command line.

We'll be using asciidoc for writing longer documents, but in general those are done by writers and engineers, who are happy with (and may well prefer) working directly with git/vi/whatever on their machines.

Gollum

This is a great idea, exactly the sort of editor we are after (though not sure we need the preview etc.). We might also want to offer ace (later) as an optional editor, for any more tech folks who use the tool (and for our designers).

pmuir commented 11 years ago

I would also like to use GFM (aka redcarpet) as it supports PHP Extra, and has the advantage of being consistent with github editing.

wesbos commented 11 years ago

Which markdown styles should we have for buttons? Possible ones that stack overflow has:

Bold
italic
link
code / backticks
headings 1-6
bulleted lis (ul)
numbered list (ol)

I know you also wanted something for tables. Will have a look at how that will work

pmuir commented 11 years ago

headers (=== and ---)
blockquote
definition list
insert image (see another issue)

On 21 Jun 2013, at 16:33, Wes Bos notifications@github.com wrote:

Which markdown styles should we have for buttons? Possible ones that stack overflow has:

• Bold • italic • link • code / backticks • headings 1-6 • bulleted lis (ul) • numbered list (ol) I know you also wanted something for tables. Will have a look at how that will work

— Reply to this email directly or view it on GitHub.

LightGuard commented 11 years ago

I'd strongly advise against using Setext headers and only allow atx headers via the buttons.

On Fri, Jun 21, 2013 at 9:36 AM, Pete Muir notifications@github.com wrote:

headers (=== and ---)

blockquote

definition list

insert image (see another issue)

On 21 Jun 2013, at 16:33, Wes Bos notifications@github.com wrote:

Which markdown styles should we have for buttons? Possible ones that stack overflow has:

• Bold • italic • link • code / backticks • headings 1-6 • bulleted lis (ul) • numbered list (ol) I know you also wanted something for tables. Will have a look at how that will work

— Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHubhttps://github.com/awestruct/web-editor/issues/12#issuecomment-19823157 .

Jason Porter http://en.gravatar.com/lightguardjp

wesbos commented 11 years ago

Yeah, I agree, ### Heading 3 is a lot cleaner and easier to implement

pmuir commented 11 years ago

No problems here :-)

Main thing is we are consistent between docs and editor.

On 21 Jun 2013, at 20:39, Wes Bos notifications@github.com wrote:

Yeah, I agree, ### Heading 3 is a lot cleaner and easier to implement

— Reply to this email directly or view it on GitHub.

mojavelinux commented 11 years ago

Pete, et al,

I recognize the importance of minimizing the technical concepts content authors must grasp in order for them to be productive without much (if any) prerequisite knowledge or training. That's precisely why I've become such a strong advocate of lightweight markup, AsciiDoc in particular.

The following statement about AsciiDoc (from above) works against our effort in the Asciidoctor project to correct the misconceptions that AsciiDoc is more complex than Markdown and only suited for longer documents:

We'll be using asciidoc for writing longer documents, but in general those are done by writers and engineers, who are happy with (and may well prefer) working directly with git/vi/whatever on their machines.

AsciiDoc is suitable for documents of any size and simpler than Markdown in two key ways:

The basic syntax (bold, italic, links, etc) in AsciiDoc is more concise than (or as concise as) Markdown
AsciiDoc does not require the use of HTML or "flavors", like Markdown does, to get essential syntax like tables, definition lists, admonitions (tips, notes, warnings, etc) and table of contents.

Let's consider a side-by-side comparison.

Basic syntax comparison (Markdown vs AsciiDoc)

Formatting	Markdown	AsciiDoc
Bold (word)	bold	bold
Bold (first letter)	bold	bold
Italic (word)	italic	_italic_
Italic (first letter)	n/a	__i__talic
Literal (word)	`literal`	+literal+ or `literal` (escaped)
Literal (first letter)	`l`iteral	++l++iteral
Link with text	[AsciiDoc](http://asciidoc.org)	http://asciidoc.org[AsciiDoc]
Image w/ Alt Text	![Logo](/images/logo.png)	image:logo.png[Logo]
Headings	## Heading 2	== Heading 2
Blockquote	> Quoted text	[quote] Quoted text
Code blocks	(GitHub-flavored Markdown) ```java public class Person { } ```	[source,java] -- public class Person { } --
Unordered list	* apples * oranges * temple * navel * bananas	* apples * oranges temple navel * bananas
Ordered list	1. first 2. second 3. third	. first . second . third

You said:

Markdown is our choice for them, as it offers a really simple syntax.

I believe these examples prove that if it's a simple syntax you are after, then AsciiDoc is the logical choice.

(Note that creating this table required the use of HTML, and formatting is not applied in the cells).

AsciiDoc has the following advantages over Markdown in these examples:

it uses the same number of markup characters or less when compared to Markdown in nearly all cases
it handles cases that Markdown doesn't (like a proper approach to inner-word markup and source code blocks)
it employs a consistent formatting scheme (one character surrounding words, two characters surrounding part of a word)
it can handle all permutations of nested inline (and block) formatting, whereas Markdown often falls down

(Asciidoctor, which is used on GitHub, also emulates "the good parts" of the Markdown syntax, like headings, blockquotes and fenced code blocks).

For more examples of AsciiDoc syntax, see: http://asciidoctor.org/docs/asciidoc-quick-reference/

Markdown fragmentation

You mentioned that you want to use Markdown extras.

I would definitely like to support Markdown Extra, as table and definition list support is important for these sorts of pages.

That's a clear indication that Markdown alone isn't sufficient. Now you have to mix and match Markdown "extras" syntax to get the features you need when they are already there in AsciiDoc...and remarkably similar.

Let's consider these two cases in AsciiDoc:

Definition Lists in AsciiDoc

a term:: a definition
another term:: another definition

They can even hold code examples:

term with code example::
description
+
[source,java]
public class Person {
}

Tables in AsciiDoc

An AsciiDoc table can be written as a series of lists which use a vertical bar as a the list marker:

[cols=3]
|===
| a
| b
| c

| 1
| 2
| 3
|===

Which appears as:

a	b	c
1	2	3

Unlike Markdown, formatting can be applied to cells (either a single format or interpreted as AsciiDoc content).

Switching markup midstream

I think your research leaves out one of the most critical usability factors for non-technical users. Regardless of how simple you make the syntax for them originally, the worst thing you can do to content authors is to make them change syntax. You don't want them to be in the middle of working on a document and require them to stop and rework everything into another syntax just because they crossed some arbitrary complexity line.

Instead, you want a smooth transition from the simple syntax used in smaller documents to the more formal syntax needed in larger documents. AsciiDoc satisfies that requirement.

In Asciidoctor, we're taking it one step further. I know people are the most familiar with Markdown. We're bringing the most popular elements of the Markdown syntax into AsciiDoc to establish a continuum and ease the initial adoption (with the exception of links and images, which I think are the worst parts of the Markdown syntax).

Conclusion

I think you should reconsider the decision to use Markdown as the default choice for authoring content and select AsciiDoc instead. In recent talks with GitHubbers, even they are entertaining the idea of switching to AsciiDoc as their default, since it offers a complete syntax that doesn't need to be hacked up to be usable (naturally they will integrate GFM into AsciiDoc for a smooth transition if they do it).

If you have any other questions about AsciiDoc or Asciidoctor, please bring them forward.

p.s. I have some additional thoughts on this topic in the following thread: http://discuss.asciidoctor.org/Asciidoc-vs-markdown-miniidoc-td269.html#a275

mojavelinux commented 11 years ago

I also want to add that I think no language has done tables that are a simple and straightforward as the ones in AsciiDoc.

...and if the pipe-separated values (psv) format shown above isn't simple enough, you can even choose to use CSV:

[format=csv]
|===
a,b,c
1,2,3
|===

mojavelinux commented 11 years ago

+1 to atx headings. se text (underline) headings waste time when creating them, add maintenance overhead (to keep the lengths up to date), look totally off if you aren't using a monospace font (which could cause someone to break them in an attempt to fix the length) and provide no hint as to which level they represent.

se text headings are a vice (esp for newcomers) and we should discourage the use of them as much as possible (for their own good).

LightGuard commented 11 years ago

My original thought was to allow the user to decide, like what Github provides: a dropdown for the syntax. Now it may only contain Markdown and AsciiDoc initially, but I don't understand why we shouldn't give the people their choice. Especially if we're talking tables you pretty much have to go with AsciiDoc (unless we're using one that supports tables, which I'm suggesting we use Kramdown, but others are saying github flavored).

At the end of the day, shouldn't we be allowing the users to use what they're comfortable using? Sure we can make suggestions, but if they're already comfortable with A (and don't need features from B), shouldn't we let them use A?

On Mon, Jun 24, 2013 at 5:36 PM, Dan Allen notifications@github.com wrote:

+1 to atx headings. se text (underline) headings waste time when creating them, add maintenance overhead (to keep the lengths up to date), look totally off if you aren't using a monospace font and don't give a hint as to which level they represent.

se text headings are a vice (esp for newcomers) and we should discourage the use of them as much as possible.

— Reply to this email directly or view it on GitHubhttps://github.com/awestruct/web-editor/issues/12#issuecomment-19943666 .

Jason Porter http://en.gravatar.com/lightguardjp

pmuir commented 11 years ago

Remember that this tool has a very tight scope, which is to make the path to develop the revamped jboss.org site for non-technical users. We do want to mandate a choice of language for them, as we want to keep this consistent across the site. Any other features we add are lower priority.

I'll think about AsciiDoc as our main markup, however one concern I still have is that the syntax is too large - one good thing about Markdown is that the syntax is limited. This is more around creating cheatsheets and docs that are suitable though - the whole asciidoc manual is going to be a problem for these people!

The other problem is that we have already gone some way down the markdown path, in terms of starting to familiarise people with the approach, and I need to think whether switching will cause a problem here.

wesbos commented 11 years ago

Which syntax do we want to use for tables? Looking at the docs, kramdown provides a few ways, this is the simplest, will it do?

| First cell | Second cell | Third cell
| First | Second | Third |
First | Second | | Fourth |

mojavelinux commented 11 years ago

I strongly recommend the simple pipe syntax if it can get the job done. That aligns well w/ the syntax in AsciiDoc and I like the two for the same reason. It doesn't require a lot of fiddling w/ the formatting.

LightGuard commented 11 years ago

+1

On Tue, Jun 25, 2013 at 5:54 PM, Dan Allen notifications@github.com wrote:

I strongly recommend the simple pipe syntax if it can get the job done. That aligns well w/ the syntax in AsciiDoc and I like the two for the same reason. It doesn't require a lot of fiddling w/ the formatting.

— Reply to this email directly or view it on GitHubhttps://github.com/awestruct/web-editor/issues/12#issuecomment-20017511 .

Jason Porter http://en.gravatar.com/lightguardjp

mojavelinux commented 11 years ago

@LightGuard In a general sense, I support having a choice of syntax (up to a point, such as 3 or 4). A single syntax will never please everyone, when considering a general audience.

If the goal is to align a group (e.g., the jboss.org content authors) to a single syntax, that's where I'm recommending that AsciiDoc is a better choice than Markdown (for reasons previously cited).

@pmuir, with regards to the concern that switching now will cause an issue, we're really only talking about the link and image syntax that's different. The rest of the training already done should apply to AsciiDoc (since Asciidoctor has Markdown compatibility in these areas). They can then be gradually shifted to the default AsciiDoc syntax (or continue using the supported Markdown syntax for a given element if everyone likes it better).

I don't understand why AsciiDoc's broader syntax has to be a strike against it. Just as you don't use every API in a programming language all at once, you won't use every syntax in a markup language all at once. You use what you need and when it comes time to do so, you use more.

Besides, new and less experienced users won't even realize the other syntax is available if it's not represented in the syntax assist buttons. They see the scope of syntax you reveal to them.

I want to be clear that I do not recommend that anyone read (or give to another to read) the AsciiDoc manual at http://asciidoc.org. The main reason is that it's really three guides in one, mixing information intended for authors, extension writers and language spec/implementation all in one document. The manual really does a disservice to the markup language, which we are trying to correct by authoring more focused guides at http://asciidoctor.org/docs.

I have been thinking about splitting the quick reference on http://asciidoctor.org into two documents, the first with a scope similar to that of Markdown and the other the remaining syntax. I could then present them together as a single reference for more seasoned users who want the whole picture. If that's a requirement for you, I'd gladly file an issue on asciidoctor.org and prioritize that split.

pmuir commented 11 years ago

@mojavelinux the concern around switching is more around being seen as chopping and changing techs. It doesn't promote confidence. The guides at asciidoctor.org look much better, and that is a good reason to change IMO. If we could do a simple/full split on the quick reference, that would be even better.

I think this seems like a good move then. I'll circle around with some folks, and confirm today or tomorrow.

LightGuard commented 11 years ago

I think we have this all sorted out, yes?

wesbos commented 11 years ago

Yep, all controls are in place. You can close this

awestruct / web-editor