Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Add WMD (Stackoverflow) style editor for content authors #12
I don't see why we couldn't support AsciiDoc, Markdown and Textile. The
On Thu, Jun 20, 2013 at 5:33 PM, Dan Allen email@example.com wrote:
Does it integrate with Tilt, or would we need to do a new tilt integration?
On Thu, Jun 20, 2013 at 11:16 PM, Dan Allen firstname.lastname@example.org:
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.
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).
On 21 Jun 2013, at 16:33, Wes Bos email@example.com wrote:
I'd strongly advise against using Setext headers and only allow atx headers
On Fri, Jun 21, 2013 at 9:36 AM, Pete Muir firstname.lastname@example.org wrote:
No problems here :-)
Main thing is we are consistent between docs and editor.
On 21 Jun 2013, at 20:39, Wes Bos email@example.com wrote:
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:
AsciiDoc is suitable for documents of any size and simpler than Markdown in two key ways:
Let's consider a side-by-side comparison.
Basic syntax comparison (Markdown vs AsciiDoc)
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:
(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/
You mentioned that you want to use Markdown extras.
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
They can even hold code examples:
Tables in AsciiDoc
An AsciiDoc table can be written as a series of lists which use a vertical bar as a the list marker:
Which appears as:
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).
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
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:
+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).
My original thought was to allow the user to decide, like what Github
At the end of the day, shouldn't we be allowing the users to use what
On Mon, Jun 24, 2013 at 5:36 PM, Dan Allen firstname.lastname@example.org wrote:
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.
On Tue, Jun 25, 2013 at 5:54 PM, Dan Allen email@example.com wrote:
@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.
@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.