Documentation

[hkdobrev]

Parsedown is approaching a stable version and it needs some kind of documentation (see #133).

Implementation

Here are possible implementations:

• Markdown files in the repository;
• Separate repository with Markdown files;
• GitHub wiki;
• HTML files in gh-pages branch.

Markdown approaches allow using the files/pages for documentation generators like https://readthedocs.org/ if needed.

I personally prefer the Markdown files to be in the same repository, because:

• Documentation could be written using the same issue tracker and pull requests like the code.
• A single pull request about a piece of code could include a related change in the documentation.

Contents

What should be documented?

I suggest:

• Public interface - most common use cases.
• Extensibility - writing your own extensions with modifications to the parsing and compiling.
• Tests structure and how/why to add more tests. Also how to test local modifications.
• Porting guide - how to easily port Parsedown to another language. E.g. Describe the algorithm.

[erusev]

Thanks for bringing this up.

Here are my concerns for the "Markdown files" approach:

• too much noise in the feed of the watchers (as I tend to be quite obsessive about editing)
• too much noise in the commit messages
• too much writing of commit messages for every little change
• too restricted

I'd vote for the third approach - GitHub wiki, as it would introduce a quick and easy way for anyone to contribute.

[hkdobrev]

Every GitHub wiki change is included in the feed of the watchers as well. There are no notifications though.

If you go with a wiki, do you plan to keep it open so anyone could help? If you plan to restrict the write access to the wiki, there would be no way to submit a pull request.

---

I've missed one approach - Markdown files in gh-branch using Jekyll.

[erusev]

If you go with a wiki, do you plan to keep it open so anyone could help?

Yes. I'd love to try that.

[hkdobrev]

@erusev Great!

What about the actual documentation content? I've outlined some ideas above.

The wiki is currently open so anyone could start the docs right away. It would be useful if we agree to some guideline though.

[barnettjw]

I found Parsedown earlier today and started playing with it.

I threw a very simple demo of Parsedown up on Runnable.

[erusev]

I added a wiki page about writing extensions.