6 ms·

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

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.

caiob 6y ago
The goal is to get more people involved. Doesn't it make sense to lower the entry barrier by implementing a more popular syntax?
- caddywompus 6y ago
  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.
- peterbe 6y ago
  It's not that easy. We have 60+k pages carried over from 15 years of organic evolution. It's unstructured and messy. A move away from HTML to something "more popular syntax" (like Markdown) is NOT easy.
gostsamo 6y ago
They are not settled on markdown, so there is time for changing their mind.
woodrowbarlow 6y ago
one of the challenges i see with this logo is that it can only be used vertically, and only quite large. here's a quick mockup of how it would look as a horizontal stack: https://i.imgur.com/S8RtqS2.png https://i.imgur.com/S8RtqS2.png with this arrangement, the character is leaning away from and pointing away from the words, and scaling down the character has made it difficult to make out the details of their pose (is that a hand? is the face empty? etc.).
- nvrspyx 6y ago
  Are we sure that's an actual logo meant to be used for anything besides maybe the repo considering it's a representation of "Yari", which is just a codename? The previous backend was codenamed "Kuma" and was represented with a bear, but wasn't displayed anywhere on the actual MDN platform.
  - callahad 6y ago
    MDN is MDN, and the branding will stay the same. Yari is a codename for the effort to move MDN closer to a static site architecture.
- caddywompus 6y ago
  Interesting, I do like the layout here, but I do agree with your points.
nathantotten 6y ago
The vast majority of docs.microsoft.com is written in markdown. This project seems be both very easy to contribute as well as produces a great docs site.
- datenarsch 6y ago
  MSDN has been around for much longer than Markdown has even existed, so I highly doubt that. Maybe the more recent stuff, which by the way is much much worse from a technical pov than their older technical documentations sadly. Compare the mess that is .NET Core / ASP.NET MVC documentation to the mostly excellent WINAPI documentation...
  - hyperrail 6y ago
    Most older pages on docs.ms.com have been converted to Markdown, and yes, that includes the Windows C and COM API docs.* Here's the source code for CreateFile's doc page: https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/fileapi/nf-fileapi-createfilew.md https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-s... Having said that, https://docs.microsoft.com https://docs.microsoft.com 's flavor of Markdown does allow for embedded HTML, like GitHub's and enough pages still use that feature that the conversion to Markdown is arguably incomplete. It isn't a big issue in practice, however; you can update markup from HTML to Markdown along with your other changes. * As a recent-past engineer on the Windows team, I have a rather lower opinion of Windows API docs than you. :) The Windows developer platform has not had enough dedicated technical writers for years; our developer content teams are mainly editors of engineer- and PM-written original docs, which can lead to API doc sets with badly written pages, important missing information, or references to Windows-internal developer tools. I tried to channel my frustrations into correcting and extending my coworkers' writings, or into gently asking them to fix their omissions when I didn't have the free time to spend on the needed research.
- caddywompus 6y ago
  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
Karunamon 6y ago
Could you explain what you mean by hindrance? As a developer documentation site, I'm having a hard time thinking of a use case that markdown doesn't support.
- shakna 6y ago
  Markdown doesn't come with basic typesetting features that you may want, such as something as basic as centering text. Other things that are critical features for development documentation, like tables, are extensions which may or may not completely break if you ever change your Markdown renderer.
  - chrisfinazzo 6y ago
    In reality, I think this concern is overblown. If you need more typesetting control than what Markdown allows, dropping down to HTML is always an option. To the second point, while it's possible that content could render differently if you change renderers, I would presume the folks at Mozilla are aware of this and won't do it unless it's absolutely necessary. Do we actually know which renderer MDN is using? I don't see this mentioned in the post. I would argue that although alternate implementations exist, Gruber's `markdown.pl` is Markdown (whatever it does, warts and all) and deviating from it is generally a bad idea if you can avoid it.
    - shakna 6y ago
      > If you need more typesetting control than what Markdown allows, dropping down to HTML is always an option. Is it? In the public setting? HTML comes with things missing from Markdown that you want, sure, but it also comes with a full scripting environment, the ability to arbitrarily inject code and so on. If you can drop to HTML, you have to have a sanitiser process. So then you're dropping to some-unknown-subset of HTML if the process is automatic - or you've failed to reduce the amount of effort being put on the editors if it's a human one.
      - chrisfinazzo 6y ago
breck 6y ago
I agree about Markdown. It's great for simple stuff, but it's very bespoke and will be limiting. I'd suggest they start with a toy I made a while back, Dumbdown as a base, and evolve from there: https://jtree.treenotation.org/designer/#standard%20dumbdown https://jtree.treenotation.org/designer/#standard%20dumbdown
- caddywompus 6y ago
  I'd never seen Tree Language designer before, this is a really cool tool! Thanks for the link
60secz 6y ago
It's sort of meta-defeatism when your resource is literally how to write html and your documentation avoids using it.
- caddywompus 6y ago
  Is it? The use of markdown is to prevent having to write out html tags for formatting. And in the end, HTML will be one of the target outputs. Even sites that accept HTML directly, are doing so through the use of a Javascript WYSIWYG editor.
yarri 6y ago
The name is cool. That logo, not so much.

caiob 6y ago

The goal is to get more people involved. Doesn't it make sense to lower the entry barrier by implementing a more popular syntax?

caddywompus 6y ago
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.
peterbe 6y ago
It's not that easy. We have 60+k pages carried over from 15 years of organic evolution. It's unstructured and messy. A move away from HTML to something "more popular syntax" (like Markdown) is NOT easy.

gostsamo 6y ago

They are not settled on markdown, so there is time for changing their mind.

woodrowbarlow 6y ago

one of the challenges i see with this logo is that it can only be used vertically, and only quite large. here's a quick mockup of how it would look as a horizontal stack: https://i.imgur.com/S8RtqS2.png https://i.imgur.com/S8RtqS2.png with this arrangement, the character is leaning away from and pointing away from the words, and scaling down the character has made it difficult to make out the details of their pose (is that a hand? is the face empty? etc.).

nvrspyx 6y ago
Are we sure that's an actual logo meant to be used for anything besides maybe the repo considering it's a representation of "Yari", which is just a codename? The previous backend was codenamed "Kuma" and was represented with a bear, but wasn't displayed anywhere on the actual MDN platform.
- callahad 6y ago
  MDN is MDN, and the branding will stay the same. Yari is a codename for the effort to move MDN closer to a static site architecture.
caddywompus 6y ago
Interesting, I do like the layout here, but I do agree with your points.

nathantotten 6y ago

The vast majority of docs.microsoft.com is written in markdown. This project seems be both very easy to contribute as well as produces a great docs site.

datenarsch 6y ago
MSDN has been around for much longer than Markdown has even existed, so I highly doubt that. Maybe the more recent stuff, which by the way is much much worse from a technical pov than their older technical documentations sadly. Compare the mess that is .NET Core / ASP.NET MVC documentation to the mostly excellent WINAPI documentation...
- hyperrail 6y ago
  Most older pages on docs.ms.com have been converted to Markdown, and yes, that includes the Windows C and COM API docs.* Here's the source code for CreateFile's doc page: https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/fileapi/nf-fileapi-createfilew.md https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-s... Having said that, https://docs.microsoft.com https://docs.microsoft.com 's flavor of Markdown does allow for embedded HTML, like GitHub's and enough pages still use that feature that the conversion to Markdown is arguably incomplete. It isn't a big issue in practice, however; you can update markup from HTML to Markdown along with your other changes. * As a recent-past engineer on the Windows team, I have a rather lower opinion of Windows API docs than you. :) The Windows developer platform has not had enough dedicated technical writers for years; our developer content teams are mainly editors of engineer- and PM-written original docs, which can lead to API doc sets with badly written pages, important missing information, or references to Windows-internal developer tools. I tried to channel my frustrations into correcting and extending my coworkers' writings, or into gently asking them to fix their omissions when I didn't have the free time to spend on the needed research.
caddywompus 6y ago
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

Karunamon 6y ago

Could you explain what you mean by hindrance? As a developer documentation site, I'm having a hard time thinking of a use case that markdown doesn't support.

shakna 6y ago
Markdown doesn't come with basic typesetting features that you may want, such as something as basic as centering text. Other things that are critical features for development documentation, like tables, are extensions which may or may not completely break if you ever change your Markdown renderer.
- chrisfinazzo 6y ago
  In reality, I think this concern is overblown. If you need more typesetting control than what Markdown allows, dropping down to HTML is always an option. To the second point, while it's possible that content could render differently if you change renderers, I would presume the folks at Mozilla are aware of this and won't do it unless it's absolutely necessary. Do we actually know which renderer MDN is using? I don't see this mentioned in the post. I would argue that although alternate implementations exist, Gruber's `markdown.pl` is Markdown (whatever it does, warts and all) and deviating from it is generally a bad idea if you can avoid it.
  - shakna 6y ago
    > If you need more typesetting control than what Markdown allows, dropping down to HTML is always an option. Is it? In the public setting? HTML comes with things missing from Markdown that you want, sure, but it also comes with a full scripting environment, the ability to arbitrarily inject code and so on. If you can drop to HTML, you have to have a sanitiser process. So then you're dropping to some-unknown-subset of HTML if the process is automatic - or you've failed to reduce the amount of effort being put on the editors if it's a human one.
    - chrisfinazzo 6y ago

breck 6y ago

I agree about Markdown. It's great for simple stuff, but it's very bespoke and will be limiting. I'd suggest they start with a toy I made a while back, Dumbdown as a base, and evolve from there: https://jtree.treenotation.org/designer/#standard%20dumbdown https://jtree.treenotation.org/designer/#standard%20dumbdown

caddywompus 6y ago
I'd never seen Tree Language designer before, this is a really cool tool! Thanks for the link

60secz 6y ago

It's sort of meta-defeatism when your resource is literally how to write html and your documentation avoids using it.

caddywompus 6y ago
Is it? The use of markdown is to prevent having to write out html tags for formatting. And in the end, HTML will be one of the target outputs. Even sites that accept HTML directly, are doing so through the use of a Javascript WYSIWYG editor.

yarri 6y ago

The name is cool. That logo, not so much.