Add supplementary example-driven documentation#1092
Add supplementary example-driven documentation#1092puzrin merged 2 commits intomarkdown-it:masterfrom
Conversation
|
@puzrin Any thoughts on the above tutorial docs? If you're not interested in keeping them, I'll close out this PR to avoid noise in the repository. Just let me know! If I don't hear anything in the next week or so, I'll opt to close this out. |
|
@puzrin One more quick ping before I close this PR: would you like to see any changes to this or is it not worth pursuing? |
|
Sorry for the silence. At the current moment, we have do mostly security/bug fixes. The topic "how to make good structured docs" is quite complicated. First, I think feedback from real developers with "fresh eyes" is a very valuable thing. But sometimes it isn't easy to fit it nicely into the existing structure. At the same time, I would not like your efforts to be lost. Since I missed all possible reaction deadlines (sorry again), I suggest landing this PR "as is", with the hope it may motivate someone to move forward in the future. I don't know if existing examples will stay in the future, will be reworked, or something else. But I'm sure rejecting those now would not be rational. I see the potential of the suggested information. That's my personal opinion. If you are okay with it, I will merge now. |
|
That makes sense and I agree! Designing good documentation is hard enough for private and closed-source projects—much more so when dealing with community-driven efforts. I take no offense if my write-ups are deleted or heavily modified down the line. Collaboration is the purpose of open-source software after all! No concerns from me, feel free to merge whenever you wish @puzrin . Thanks for your work on this library! |
I've spent the past several weeks working on a markdown-it plugin that adds shortcuts relevant to Tufte CSS.
In the process I've learned a ton about developing robust Markdown-It plugins, and I'd like to share some of those learnings with the community.
So far I've only written up one tutorial doc. I'm opening this PR to get some early eyes on it, to see if it's a relevant or desired type of contribution.
If it is, I intend to write a few more of these outlining some other learnings from my development experience.
Thank you all for your work on this library!