Sorry, I must not have explained myself well enough. For dtdocs, we have
pretty much chosen our tool chain, and we intentionally did not announce
anything to avoid this type of bike shedding.
While markdown has its negatives, the positive is that if you've written
a comment on the internet in the last several years, you've probably
written markdown, if you know so or not.
By "actionable criticism," I meant please make sure your criticism is
applicable and actionable on the current dtdocs project. I don't think
we're interested in generalized markup discussion, tool chain
discussions, or any thing else of that sort. Again, the decisions have
been made. If you feel we've absolutely made the wrong decision with
markdown, you're free to fork the repo, convert it to the markup flavor
that suits you, and edit the content there.
We won't use RTD since the point is that we host the documentation
ourselves. Hugo gives us a pretty simple and straight forward way to
publish things, the dependencies are very minimal, and it integrates
well into CI systems. If you feel that things are missing, please open
an issue, but the sentiment of "eventually it'll be missing something
because tool XYZ is better" isn't really helpful.
For context: my profession is documentation and has been for the last 12
years. I've maintained large documentation sets in LaTeX, docbook, DITA
XML, FrameMaker, and more. I've maintained docs using just git and I've
maintained them using proprietary systems that cost millions of dollars.
I've architected new documentation sets that covered hundreds of
products and customized the publishing pipeline around them.
- mica
On 10/16/20 5:13 PM, Moritz Moeller wrote:
On 17.10.20 01:41, Mica Semrick wrote:
You have specifically pointed out where you think markdown is falling
short in this case.
For me MD vs Sphinx is mostly about roles, extensions, citations, line
comments, footnotes etc. that you have in Sphinx but not in MD.
MD was designed for writing texts on the Web. ReST + Sphinx was designed
for writing documentation.
Here is a longer version of that, written by someone else:
https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
With that said: I prefer MD syntax over ReST any day as long as it
doesn't take anything away I think is standard for good documentation.
E.g. being able to have an index auto-generated.
Sadly it does. Worst, there is no real standard in MD.
CommonMarkdown is different everywhere. Maybe a feature you grew fond of
when using MD in Jupyter Notebooks' MD is not available on GiHub's MD etc.
> Feedback is welcome, but please try to make it actionable. We're
> aiming for improvement.
With the above in mind – if I were to start a documentation project now
I'd probably use this:
https://myst-parser.readthedocs.io/en/latest/
Which is kinda ReST + MD having a baby. :)
It would mean all the work you done could be used, mostly as-is.
But you would have all the bonuses of ReST + Spinx on top that MD +
Sphinx would not give you. Even if you switched from MD + Hugo to MD +
Sphinx.
Oh, and use readthedocs to handle building and serving.
Because, again, that is an ecosystem build for serving documentation as
static pages online.
Hugo is nice but it was meant to build static websites.
Which surely represent a superset, containing static online
documentation, but broad enough that it will leave many things to be
desired, sooner or later.
And btw: https://darktable.readthedocs.io/ is available. ;)
Beers,
.mm
P.S.: For context:
I wrote software documentation in MD several times during the last decade.
I wrote software documentation in ReST using Sphinx several time (that
was before Sphinx added MD support).
I also have BG writing docs in LaTex from way before.
With that being said I feel entitled to be opinionated about the subject.
And mind you, I am talking about the perspective of the writer, not the
user.
___________________________________________________________________________
darktable developer mailing list
to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
___________________________________________________________________________
darktable developer mailing list
to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
