14
votes
Alternatives to Markdown for writing short documentation/TODOs?
Hi guys,
I often find myself writing small text files for projects, like a bit of documentation or TODOs. I have a proper system in place for larger projects, but would love to be able to scribble down things for larger ones.
As big of a fan of Markdown as I am, I find that it's often inappropriate for these kinds of tasks. For example, I find myself mimicking a task list with multiple-paragraph list items.
What do you guys use? Do you know of any Markdown alternatives that give you a bit more control over the layout?
Thanks!
Maybe an unpopular suggestion (because it's difficult to implement) and reading between the lines I think you might want an easier answer. That's fine, but I'm suggesting this also for the wider community and to introduce a tool that is difficult to pick up but the rewards are immense.
org-mode > any text utility used for organising any/everything.
That may sound like hyperbole but it really isn't. The downside is that it's only for emacs and it's quite an investment - emacs isn't easy to pick up. I've read that some people only started using emacs specifically because of org-mode.
The org-mode wiki is about the best place to start but I started by started watching Rainer König's comprehensive tutorials.
I started using emacs, about a year ago, mostly because of orgmode. Now I use emacs for coding and in the future I'm going to use it for writing latex.
But emacs takes a lot of its user time. Only use it if you are willing to learn it.
I don't care what tools people use, its a personal choice, but I think emacs is really misunderstood.
People are (quite rightly) put off by the arcane terminology and frankly byzantine look and conventions and default configuration. Luckily people create and publish starter packs, with more user friendly looks and initial feature sets.
Instead of thinking of it as an editor, a better model is to think of it as a live, programmable environment for manipulating buffers of text (usually). (Lisp also puts a lot of people off too. but I like it.) Once you understanding what using a Lisp machine can be like and that practically everything can be configured, tweaked and manipulated to do exactly what you want without waiting for the maintainers to implement things for you, it really becomes the most incredibly powerful tool. People maintain and tweak their configurations indefinitely because it grows organically with your understanding.
As you say it is a heavy time/habit investment and a steep learning curve.
If I haven't lost or bored everyone to death already, I can't recommend Mickey Peterson's book Mastering emacs highly enough. Even after several years of using emacs I learned so much from that book, in part because it teaches you how to learn from the incredible help system built into emacs itself.
Well, if you don't like Markdown's:
Then you might look into todo.txt, it's a format with a couple dozen clients for handling it (So you can get even more complicated interconnecting tasks). Works with version control well.
What would you do in Markdown if you had to specify more info for each task, such as a description and a quote for example?
I often have this problem with other kinds of lists too — specifying more information for an item, even though the item is not big enough to be a heading.
Thanks for the link to todo.txt!
Indent and bulletpoint.
Markdown allows you to nest it's formatting.
Like others mentioned, Markdown is probably your best bet, with a nested task list.
If you're looking for something more complex, reStructuredText might suit your needs, (here's a comparison), although it's more complicated.
Maybe you could also look into LaTeX, although that's also more complicated and not really suited for small notes and todos.
What I do is I write in MarkDown (+ HTML or LaTeX in-line, when needed) and then use Pandoc to convert that in any other format (e.g. PDF through LaTeX). Works like a charm! Especially for throwing together a quick and lazy slideshow ;)
AsciiDoc is similar in style to Markdown, but it is a lot more comprehensive.
The lists support labels, wrapping, line continuation and other complex content.
Yes, this is great! Thank you.
I use markdown with gollum, it's perfect for me especially since the new version includes pandoc so I can put even a bibliography in .bib format for some of the more developed projects. Plus it's markdown but looks nice on your browser (I think it also renders the [ ] like github). Gollum also accepts a few other formats that I don't remember off the top of my head but you could check the github project, it may be interesting to you!
Have you looked into project management apps on the web like asana, trello, freedcamp, etc.?
It sounds like what you're doing is tracking task items and it seems a bit cumbersome to do that all in text. While these are much smaller scale than most projects, being able to quickly visualize, set goal dates, etc. might be useful.