5 ms·

I want to use markdown for our technical documents. But MS Word really has some features that are missing that would be needed for a markdown editor to make a d

I want to use markdown for our technical documents. But MS Word really has some features that are missing that would be needed for a markdown editor to make a dent in what we need. 1. auto-generating table of contents 2. easy table creation/manipulation 3. header/footer and page numbering 4. comments/edits (maybe integrated with git?) It's unrealistic to expect non-technical people to learn LaTeX, so we're stuck with MS Word until someone makes an amazing Markdown editor that can handle these things.

drodil 9y ago
Very good point. There would be an awesome opportunity for some software engineer to create such editor (cross-platform of course). Also it could support other markup languages such as Textile as they don't differ from each other so much. Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box.
- xienze 9y ago
  > Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box. There is technically a standard Markdown dialect called CommonMark. The main problem with it is that its specification is example-driven and there's lots of places where things are up for interpretation, but for the most part it achieves its goal. What it really needs is standardization of extensions like tables, diagrams, etc.
j_4 9y ago
3. is automatically added and easy to adjust when using the Markdown PDF extension for VS Code.[1] [1]: https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf https://marketplace.visualstudio.com/items?itemName=yzane.ma...
oneeyedpigeon 9y ago
Well, markdown files are just plain text, so you get the git integration 'for free'. As for 2&3, this is why I author documents in HTML: about the same level of complexity as MD, but far, far more powerful. 1, I'll give you, is an issue, just one I don't even run into (I tend not to be editing documents so huge that they demand a ToC).
- geogra4 9y ago
  We do a lot of large design/spec documents so we really make a lot of use of that.
  - oneeyedpigeon 9y ago
    I think if I had that use-case, I would consider writing a small piece of javascript to generate the ToC. Maybe even possible with CSS, although it could well be too hack-ish for that approach.
cup-of-tea 9y ago
Org-mode can do all of those things.
- geogra4 9y ago
  Emacs is going to be just as obtuse for your everyday business analyst as LaTeX
  - eadmund 9y ago
    The original emacs paper[0] noted that many of the users who started programming were secretaries who didn't know that they could. Learning how to truly use a computer is as important in the 21st century as learning to read was in the 19th: those who find emacs obtuse need to learn it just as certainly as those who found letters confusing. [0] https://www.gnu.org/software/emacs/emacs-paper.html#SEC29 https://www.gnu.org/software/emacs/emacs-paper.html#SEC29
    - cup-of-tea 9y ago
      Yes, it is unfortunate that so many use computer-shaped devices but only a very small number actually do computing. The rise of point-and-click has done a really good job of hiding the possibilities from people. Eben Moglen likened point-and-click to a "caveman interface" where your only options are pointing and grunting, as opposed to using language to communicate your ideas. Only programmers do the latter but that is a shame.
      - deckard1 9y ago
        > Only programmers do the latter but that is a shame. Part of me says this is job security for software developers. The other part of me saw non-programmers try to use Excel as a layout/desktop publishing/vector graphics tool. But seriously, if you know how to program and you do literally anything else, then you become a developer. It's the cushiest job with the highest pay. The other reason it will never happen is because the developer's job isn't to make the office worker more efficient (that's Microsoft's job, so I suppose some developer does it, just not all developers). The developer's job is to increase efficiency. Either internal efficiency, or external efficiency. And that means: jobs will be lost. Rather than training office workers how to program and have them leave for a developer job, it's better to just pay developers and have them automate an entire class of office workers' jobs. Hopefully all developers get the opportunity to witness internal efficiency planning. Most developers are disconnected from the process. But to actually meet the people you're going to eliminate with software in a month or two is truly something.
adzicg 9y ago
"pandoc --toc" puts a TOC in when creating pdf files. You can also use "--toc-depth=XXX" to select how many levels of headings you want in the toc. page numbers also get added automatically I think when using the book docclass.
lloeki 9y ago
Our needs are simple, so we have something† based on kramdown (in GFM mode) and tilt-pdf[0] (shameless plug) which generates a TOC, handles styles, headers/footers, and leverages wkhtmltopdf††. Documentation is in git as markdown files, linted, generated, and published as part of CI/CD. Comments/edits are done though GitLab MRs implementing an editorial review process. Occasional contributions are done through GitLab web editor, and more involved non-technical people use VSCode to sync, write, and commit. The GitLab flow of (Issue->Branch->MR)->(Fetch->Edit->Commit->Push)->(Review->Merge->Publish) is quite assisted and works quite well with open-minded non-tech people. [0]: https://github.com/lloeki/tilt-pdf https://github.com/lloeki/tilt-pdf † The tool should be open-sourced as soon as we can clean up the code of hardcoded internal stuff. It'll appear over there: https://github.com/adhoc-gti/makebook https://github.com/adhoc-gti/makebook †† Contemplating moving to headless Chrome. Also, increasingly using Hugo for online documentation.
- geogra4 9y ago
  This looks really neat! I'd love to experiment with this
- pzb 9y ago
  I've been working on a similar system that is in the process of being adopted by at least one standards group (https://github.com/cabforum/documents https://github.com/cabforum/documents ). I would strongly recommend looking at weasyprint (http://weasyprint.org/ http://weasyprint.org/ ) for HTML to PDF. It gives much better PDF output and offers CSS print support, so you get page control.
shadowfiend 9y ago
asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something like GitHub, tables (https://asciidoctor.org/docs/user-manual/#tables https://asciidoctor.org/docs/user-manual/#tables), tables of contents (https://asciidoctor.org/docs/user-manual/#user-toc https://asciidoctor.org/docs/user-manual/#user-toc), and with some docbook work (admittedly annoying), you can get header/footer and page number (https://asciidoctor.org/docs/user-manual/#docinfo-file https://asciidoctor.org/docs/user-manual/#docinfo-file). It's not perfect, but it's very similar in concept to Markdown, has several adaptations to make the md->adoc transition easier, and is much more feature-rich, thanks to being based on Docbook (which is used for creating much more complicated documents than Markdown historically has been).
- castillar76 9y ago
  Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.

drodil 9y ago

Very good point. There would be an awesome opportunity for some software engineer to create such editor (cross-platform of course). Also it could support other markup languages such as Textile as they don't differ from each other so much. Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box.

xienze 9y ago
> Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box. There is technically a standard Markdown dialect called CommonMark. The main problem with it is that its specification is example-driven and there's lots of places where things are up for interpretation, but for the most part it achieves its goal. What it really needs is standardization of extensions like tables, diagrams, etc.

j_4 9y ago

3. is automatically added and easy to adjust when using the Markdown PDF extension for VS Code.[1] [1]: https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf https://marketplace.visualstudio.com/items?itemName=yzane.ma...

oneeyedpigeon 9y ago

Well, markdown files are just plain text, so you get the git integration 'for free'. As for 2&3, this is why I author documents in HTML: about the same level of complexity as MD, but far, far more powerful. 1, I'll give you, is an issue, just one I don't even run into (I tend not to be editing documents so huge that they demand a ToC).

geogra4 9y ago
We do a lot of large design/spec documents so we really make a lot of use of that.
- oneeyedpigeon 9y ago
  I think if I had that use-case, I would consider writing a small piece of javascript to generate the ToC. Maybe even possible with CSS, although it could well be too hack-ish for that approach.

cup-of-tea 9y ago

Org-mode can do all of those things.

geogra4 9y ago
Emacs is going to be just as obtuse for your everyday business analyst as LaTeX
- eadmund 9y ago
  The original emacs paper[0] noted that many of the users who started programming were secretaries who didn't know that they could. Learning how to truly use a computer is as important in the 21st century as learning to read was in the 19th: those who find emacs obtuse need to learn it just as certainly as those who found letters confusing. [0] https://www.gnu.org/software/emacs/emacs-paper.html#SEC29 https://www.gnu.org/software/emacs/emacs-paper.html#SEC29
  - cup-of-tea 9y ago
    Yes, it is unfortunate that so many use computer-shaped devices but only a very small number actually do computing. The rise of point-and-click has done a really good job of hiding the possibilities from people. Eben Moglen likened point-and-click to a "caveman interface" where your only options are pointing and grunting, as opposed to using language to communicate your ideas. Only programmers do the latter but that is a shame.
    - deckard1 9y ago
      > Only programmers do the latter but that is a shame. Part of me says this is job security for software developers. The other part of me saw non-programmers try to use Excel as a layout/desktop publishing/vector graphics tool. But seriously, if you know how to program and you do literally anything else, then you become a developer. It's the cushiest job with the highest pay. The other reason it will never happen is because the developer's job isn't to make the office worker more efficient (that's Microsoft's job, so I suppose some developer does it, just not all developers). The developer's job is to increase efficiency. Either internal efficiency, or external efficiency. And that means: jobs will be lost. Rather than training office workers how to program and have them leave for a developer job, it's better to just pay developers and have them automate an entire class of office workers' jobs. Hopefully all developers get the opportunity to witness internal efficiency planning. Most developers are disconnected from the process. But to actually meet the people you're going to eliminate with software in a month or two is truly something.

adzicg 9y ago

"pandoc --toc" puts a TOC in when creating pdf files. You can also use "--toc-depth=XXX" to select how many levels of headings you want in the toc. page numbers also get added automatically I think when using the book docclass.

lloeki 9y ago

Our needs are simple, so we have something† based on kramdown (in GFM mode) and tilt-pdf[0] (shameless plug) which generates a TOC, handles styles, headers/footers, and leverages wkhtmltopdf††. Documentation is in git as markdown files, linted, generated, and published as part of CI/CD. Comments/edits are done though GitLab MRs implementing an editorial review process. Occasional contributions are done through GitLab web editor, and more involved non-technical people use VSCode to sync, write, and commit. The GitLab flow of (Issue->Branch->MR)->(Fetch->Edit->Commit->Push)->(Review->Merge->Publish) is quite assisted and works quite well with open-minded non-tech people. [0]: https://github.com/lloeki/tilt-pdf https://github.com/lloeki/tilt-pdf † The tool should be open-sourced as soon as we can clean up the code of hardcoded internal stuff. It'll appear over there: https://github.com/adhoc-gti/makebook https://github.com/adhoc-gti/makebook †† Contemplating moving to headless Chrome. Also, increasingly using Hugo for online documentation.

geogra4 9y ago
This looks really neat! I'd love to experiment with this
pzb 9y ago
I've been working on a similar system that is in the process of being adopted by at least one standards group (https://github.com/cabforum/documents https://github.com/cabforum/documents ). I would strongly recommend looking at weasyprint (http://weasyprint.org/ http://weasyprint.org/ ) for HTML to PDF. It gives much better PDF output and offers CSS print support, so you get page control.

shadowfiend 9y ago

asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something like GitHub, tables (https://asciidoctor.org/docs/user-manual/#tables https://asciidoctor.org/docs/user-manual/#tables), tables of contents (https://asciidoctor.org/docs/user-manual/#user-toc https://asciidoctor.org/docs/user-manual/#user-toc), and with some docbook work (admittedly annoying), you can get header/footer and page number (https://asciidoctor.org/docs/user-manual/#docinfo-file https://asciidoctor.org/docs/user-manual/#docinfo-file). It's not perfect, but it's very similar in concept to Markdown, has several adaptations to make the md->adoc transition easier, and is much more feature-rich, thanks to being based on Docbook (which is used for creating much more complicated documents than Markdown historically has been).

castillar76 9y ago
Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.