caddywompus

Interesting, I didn't know that. I'll check it out, since I'd like to see if they add any of their own extensions, in the same way that Github does

Yes, that's definitely the balance to maintain. Ease of entry, vs tooling to manage the project as it grows. The main reason I see it being an inhibition is due to the size of the HTML spec, and the number of pages that it will need.

I think this is why a lot of sites take markdown, then add their own extensions, like how there is "Github Markdown" among many other flavors. That's definitely one route, but I see something like ReStructuredText or Asciidoc as more mature and interoperable, while still being relatively easy to master in the same way as Markdown. Since they can both produce docbook output, vastly easing any migrations in the future by adhering to an industry standard.

Interesting, I do like the layout here, but I do agree with your points.

Well the beauty of Markdown, is that it doesn't specify a lot of functionality, making it easy to understand. But when you have many, many pages of documentation, you will need to start linking them together in meaningful ways.

This is where is becomes useful to have tools that can generalize things. For example, say you link to another page in your documentation repository, in Markdown, you create a link either with an absolute or relative path, specifying the filename and optionally anchor on that page. Now later down the road, you edit the folder hierarchy, or rename a page, you will now need to find all references and update them manually.

Something like ReStructuredText has the "interlink" module, which allows you to modularize your pages, and use symbolic names instead of the relative or absolute path. Now, there are pros and cons to each approach, i.e. if you have a good set of tools, doing a global search and replace across documents can deal with this too. But having the flexibility of things like symbolic names and macros can make things much more manageable.

Of course, this is a double edged sword, in that you can customize, create macros, until you now have a monster in of itself, but that can be said of any tool.

I tend to see Markdown as perfect for standalone documents, and its especially good for formatting internet comments and the likes.

Tools like DocBook and other XML processors attempt to provide the maximum amount flexibility, and the cost of a steep learning cliff and lots of boilerplate, but if implemented well, it can allow things like conditionally including parts of documentation based on tags, or output formats, but definitely requires extensive tooling as opposed to Markdown and other formats that are meant to be readable in their source form.

It's odd though, they have these contradictory actions. For the iPhone, they are pushing for privacy, but on MacOS, we are now dealing with things like excessive telemetry to the point of phoning a authorization server for running local binaries. Not to mention the new firewall issues, where Apple utilities are able to bypass local firewall rules.

Really glad to see this project continuing on. I do have concerns about being limited to Markdown syntax though. While Markdown has its place on small to medium sized projects, its simplicity quickly becomes a hindrance, and you end up falling back to html in Markdown. I could see something like ReStructuredText or Asciidoc being a better fit, if not a full blown enterprise style Docbooks or DITA system.

Not a big fan of the logo, it is cool, but doesn't really inspire my inner web documentation. (edit) Actually no, I think its the size and style of the logo. Singling out the top of the spear and using that would be cool, but it reminds me too much of a fighting game character as is.