search

manubot / rootstock

Clone me to create your Manubot manuscript
https://manubot.github.io/rootstock/
Other
451 stars 176 forks source link

Improved documentation #288

Open Nebucatnetzer opened 4 years ago

Nebucatnetzer commented 4 years ago

Are there any ideas floating around regarding an improved documentation?

dhimmel commented 4 years ago

Right now documentation is scattered between READMEs, USAGE.md, SETUP.md, content/02.delete-me.md and the python package README and autogenerated docs. Consolidating these docs to whatever extent makes sense is something we think about. We're also looking to simplify how Manubot works and how many files it requires... so this could simplify the documentation task.

Are there any holes in the documentation that you'd like to let us know about?

vincerubinetti commented 4 years ago

In short, I just want to say: I'm on it. As Daniel said, we're in the process of simplifying Manubot itself, so it made sense to sort of hold off on the full documentation until that was complete, because it will change a lot.

Coming from a UI/UX designer perspective, I'm keenly aware that the current documentation is lacking, and what a nice, comprehensive doc set looks like.

Nebucatnetzer commented 4 years ago

To give some context, I'm currently trying to recreate my thesis (written in latex) with manubot to have some sort of real life example. I just noticed that I'm hopping around a lot to find stuff (from USAGE.md to issues, to pandoc, to common mark, etc). One example was adding page breaks which I didn't found in the USAGE.md but found an issue (#35) about it and the option was actually quite nice. Other things I thought about and didn't find in USAGE.md were: mathjax (found it in build.sh), toc, footnotes, glossary.

However I'm unsure about what you want to include in Manubot since I've read somewhere that it is more intended to be for reviews which might exclude a thesis like mine (it's not an academic paper).

As for the shifting nature of the project. How about something simple, like the repo wiki here on Github? It's not pretty and IMO a bit limited if the project grows to much but written in Markdown and easy to use. The auto generated docs look great of course.

vincerubinetti commented 4 years ago

:thumbsup: definitely. A road map would be a good thing to state upfront clearly too, so people don't have to go through hundreds of github issues to see if we're even going to attempt doing a certain feature.

Nebucatnetzer commented 4 years ago

I see we're on the same page here :), for the road map maybe the Kanban board might be useful? If you already know some things which you won't include it might be good to create issues and close them right away with "wontfix".

Should I add things like the page break to the USAGE.md file to begin with so that they are a bit easier to find and don't get lost until a proper solution was found for the documentation?

vincerubinetti commented 4 years ago

I think we'd all welcome any PR you'd like to contribute in the meantime!

dhimmel commented 4 years ago

To give some context, I'm currently trying to recreate my thesis (written in latex) with manubot to have some sort of real life example.

Cool. If the goal is to create a public venue where your thesis can be viewed and its source inspected, then Manubot will be great. If you need to produce a very specific formatting to satisfy certain dissertation styling guidelines, that could be difficult. If you get this to work, feel free to add your thesis to the catalog (not sure we have a thesis made with manubot yet, would be cool).

Should I add things like the page break to the USAGE.md

Looking over usage, it is missing a reference to 02.delete-me.md like we have briefly in the paper describing manubot:

A list of formatting options officially supported by Manubot, at the time of writing, is viewable as raw Markdown and the corresponding rendered HTML.

There's a lot of formatting stuff we document by example in 02.delete-me.md. However, it doesn't look like we include page breaks in it. Therefore, perhaps we want to document page breaks in delete-me and also more clearly reference delete-me in USAGE. @Nebucatnetzer any amount of help you want to provide in this regard would be appreciated!

vincerubinetti commented 4 years ago

Just for reference, here are some examples of what I think is good documentation. I'll add more as I think of them.

https://github.com/downshift-js/downshift https://reactjs.org/docs/getting-started.html

React also has amazing error messages that are simple, and tell you exactly what to do to fix the problem. I'll post examples of those too, when/if we have an issue about improving the error messages.

Good documentation is written in plain language, not overly academic or obtuse. It covers the basic use cases first, allowing people seeing it for the first time to instantly understand what's going on. It makes it easy to find what you're looking for, just by looking at headings. But it also allows people who need more detailed information to dive into a more specific section.

Nebucatnetzer commented 4 years ago

Cool. If the goal is to create a public venue where your thesis can be viewed and its source inspected, then Manubot will be great. If you need to produce a very specific formatting to satisfy certain dissertation styling guidelines, that could be difficult. If you get this to work, feel free to add your thesis to the catalog (not sure we have a thesis made with manubot yet, would be cool).

The idea was more to achieve the second task. We'll see how far I get :)

Looking over usage, it is missing a reference to 02.delete-me.md like we have briefly in the paper describing manubot:

Ah yes that's what I was looking for, didn't even saw that file. Happens when you follow instructions blindly...