Re: Feedback request | Documentation site reorg, switch to Markdown
On Fri, Mar 3, 2017 at 11:19 AM, Robert Young wrote: > Hi Simon, > > I agree with your assessment. Standard markdown lack some of the > features that make technical writing easy to read, however, there are > several extensions to markdown that make it better. Although I really > like DO's extension, I'm not sure it is a free spec. I know for sure > that it is not a common spec. On the other hand, Pandoc > (http://pandoc.org) is a wonderful tool that you can get from the > standard repos. It has extensions for syntax highlighting, inline html, > and, most importantly, can convert text from markdown (and dozens of > other formats) to DocBook and vice versa. I think even if we leave > DocBook as the official markup choice, Pandoc can be referred to as a > way for contributors to use the tools they feel most comfortable with, > but still contribute. I would have to do some testing on the fidelity of > the format output to what the existing documentation looks like. If this > is of interest, let me know, and I will start running some tests. > > I'm well aware of pandoc. It's what I used a few years back when I tried to get the Server Guide converted to RST. It is also the tool that we use in Canonical to convert stuff. It never converts perfectly. There is always collateral damage that requires fiddling with. Elsewhere in this thread a similar idea was proposed: users write in their preferred format and conversion happens afterwards by a Doc committer. If it's the writer instead then they are free to do what they want with their time. I'd also like to mention that in Canonical we do extend the standard GitHub Markdown. Peter -- ubuntu-translators mailing list ubuntu-translators@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
RE: Feedback request | Documentation site reorg, switch to Markdown
Hi Robert, Simon, Both very useful e-mails thanks. Robert: for unknown reasons (it is not in the held queue) your e-mails do not get to the docs e-mail list (or the translators one, I think), so this reply is also to get it there. Note: e-mails from some others are not getting to all copied lists either. (See rt.ubuntu.com #29630). That site you referenced, http://pandoc.org seems like it might be a useful tool. I do not know the differences between "Markdown" and "GitHub Flavored Markdown", so don't know if it'll work on what Peter is proposing. I'll leave it to Peter to reply if he wants you do some testing or not. On 2017.03.03 08:20 Robert Young wrote: > Hi Simon, > > I agree with your assessment. Standard markdown lack some of the > features that make technical writing easy to read, however, there are > several extensions to markdown that make it better. Although I really > like DO's extension, I'm not sure it is a free spec. I know for sure > that it is not a common spec. On the other hand, Pandoc > (http://pandoc.org) is a wonderful tool that you can get from the > standard repos. It has extensions for syntax highlighting, inline html, > and, most importantly, can convert text from markdown (and dozens of > other formats) to DocBook and vice versa. I think even if we leave > DocBook as the official markup choice, Pandoc can be referred to as a > way for contributors to use the tools they feel most comfortable with, > but still contribute. I would have to do some testing on the fidelity of > the format output to what the existing documentation looks like. If this > is of interest, let me know, and I will start running some tests. > > Robert > > On Fri, Mar 03, 2017 at 12:43:11PM +0200, Simos Xenitellis wrote: >> On Fri, Feb 24, 2017 at 2:22 PM, Chris Perry >> wrote: >>> Hi Peter >>> >> ... >>> >>> You used the term PITA (pain in the arse, I think). I (kind of) agree >>> with what you said about server guide xml being a PITA. All markup >>> languages are (kind of) a PITA. The problem I have with your proposal >>> is that (as far as I can see) you're moving from one PITA (server >>> guide xml) to another PITA (Markdown). >>> >> >> Digitalocean are using Markdown for their online tutorials. >> >> Compared to the standard markdown >> (https://guides.github.com/features/mastering-markdown/), >> they have added some extra features that are suitable for technical >> documentation. >> Here is their Writing Guidelines, >> https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines >> which shows off their additions (second-half of the page). >> >> Among the useful features they have added to Markdown (see Writing >> Guidelines), >> 1. Ability to highlight text even in a code environment (for example, >> in some configuration you can easily highlight the stuff that the user >> needs to write) >> 2. Ability to show the command line in five different environment >> (themes?). If you show commands that you write on Server A, you can >> specifically use Theme 1 and so on. >> 3. Ability to show the output of commands in a suitable environment >> (and also can highlight aspects of that output) >> 4. Native notes and warnings (in standard markdown, you would need to >> insert HTML for this) >> 5. Have the prompt ($ or #) added appropriately because we define that >> a command line is for superuser or plain user. Also, custom prompts. >> >> There is the Web previewer to try these out at >> https://www.digitalocean.com/community/markdown >> >> I believe that the standard markdown, as described on github, is not >> suitable for technical documentation as it lacks features. >> An enhanced markdown would be more appropriate and more joyful to >> write documentation. >> >> For me the questions are, >> a. what "enhanced markdown" can we get that is at least on parity with >> Docbook XML features. >> b. is there some tool to autoconvert Docbook XML to markdown? >> c. will existing core technical writers be happy to switch to markdown? >> >> Simos -- ubuntu-translators mailing list ubuntu-translators@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Re: Feedback request | Documentation site reorg, switch to Markdown
On Fri, Feb 24, 2017 at 2:22 PM, Chris Perry wrote: > Hi Peter > ... > > You used the term PITA (pain in the arse, I think). I (kind of) agree > with what you said about server guide xml being a PITA. All markup > languages are (kind of) a PITA. The problem I have with your proposal > is that (as far as I can see) you're moving from one PITA (server > guide xml) to another PITA (Markdown). > Digitalocean are using Markdown for their online tutorials. Compared to the standard markdown (https://guides.github.com/features/mastering-markdown/), they have added some extra features that are suitable for technical documentation. Here is their Writing Guidelines, https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines which shows off their additions (second-half of the page). Among the useful features they have added to Markdown (see Writing Guidelines), 1. Ability to highlight text even in a code environment (for example, in some configuration you can easily highlight the stuff that the user needs to write) 2. Ability to show the command line in five different environment (themes?). If you show commands that you write on Server A, you can specifically use Theme 1 and so on. 3. Ability to show the output of commands in a suitable environment (and also can highlight aspects of that output) 4. Native notes and warnings (in standard markdown, you would need to insert HTML for this) 5. Have the prompt ($ or #) added appropriately because we define that a command line is for superuser or plain user. Also, custom prompts. There is the Web previewer to try these out at https://www.digitalocean.com/community/markdown I believe that the standard markdown, as described on github, is not suitable for technical documentation as it lacks features. An enhanced markdown would be more appropriate and more joyful to write documentation. For me the questions are, a. what "enhanced markdown" can we get that is at least on parity with Docbook XML features. b. is there some tool to autoconvert Docbook XML to markdown? c. will existing core technical writers be happy to switch to markdown? Simos -- ubuntu-translators mailing list ubuntu-translators@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
