Roller Documentation from ODT to md (markdown)
Hello team, During my exploration for documentation, I found the documentation link [1] on Roller home page [2] under the Documentation section. I see, currently, we are storing the documents in odt format. I would like to know the thoughts of the community on moving the documentation from .odt to .md We will have the following advantage if we use md format - 1. Rendering support of md file on GitHub The GitHub nicely render the md files, so if the files in md format, it will be easily rendered on GitHub. The odt files don't have any preview on GitHub and it forces the user to download to view the content. (This is annoying for the user and developers ;-) e.g. https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt 2. Easy to maintain, the md standard is widely accepted The md format is widely used and this will open up the opportunity for new collaborators to participate. Kindly let me know if I am missing any information or history or purpose for maintaining our docs in .odt format. P.S. I see we are also maintaining the pdf version of odt [3] in master branch. The conversion from md to pdf is also doable. IMO, if we move our documents to md version, the pdf conversation will be no longer required since it will be rendered on GitHub properly. (Still, if I am missing anything, please feel free to comment :-) [1] https://github.com/apache/roller/tree/roller-5.2.0/docs [2] http://roller.apache.org/ [3] https://github.com/apache/roller/tree/master/docs Best regards, Swapnil M Mane, www.apache.org
Re: Roller Documentation from ODT to md (markdown)
I think that's a great idea and the docs, or a least the screenshots, need update for the new Roller 6 UI. Markdown is better for this in so many ways. AsciiDoc is also a good option but I don't have a strong preference on Markdown vs. AsciiDoc. Dave On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane wrote: > Hello team, > During my exploration for documentation, I found the documentation > link [1] on Roller home page [2] under the Documentation section. > I see, currently, we are storing the documents in odt format. > > I would like to know the thoughts of the community on moving the > documentation from .odt to .md > > We will have the following advantage if we use md format - > > 1. Rendering support of md file on GitHub > The GitHub nicely render the md files, so if the files in md format, > it will be easily rendered on GitHub. > The odt files don't have any preview on GitHub and it forces the user > to download to view the content. (This is annoying for the user and > developers ;-) > e.g. > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt > > 2. Easy to maintain, the md standard is widely accepted > The md format is widely used and this will open up the opportunity for > new collaborators to participate. > > Kindly let me know if I am missing any information or history or > purpose for maintaining our docs in .odt format. > > P.S. I see we are also maintaining the pdf version of odt [3] in master > branch. > The conversion from md to pdf is also doable. > IMO, if we move our documents to md version, the pdf conversation will > be no longer required since it will be rendered on GitHub properly. > (Still, if I am missing anything, please feel free to comment :-) > > [1] https://github.com/apache/roller/tree/roller-5.2.0/docs > [2] http://roller.apache.org/ > [3] https://github.com/apache/roller/tree/master/docs > > Best regards, > Swapnil M Mane, > www.apache.org >
Re: Roller Documentation from ODT to md (markdown)
Great, thanks Dave. Thoughts travels, while drafting the mail, AsciiDoc was also in my mind. And AsciiDoc is also having all the advantages mentioned above. After some more exploration, I am now more inclined towards AsciiDoc. So, +1 for AsciiDoc. Best regards, Swapnil M Mane, www.apache.org On Tue, Aug 27, 2019 at 8:53 PM Dave wrote: > > I think that's a great idea and the docs, or a least the screenshots, need > update for the new Roller 6 UI. Markdown is better for this in so many > ways. AsciiDoc is also a good option but I don't have a strong preference > on Markdown vs. AsciiDoc. > > Dave > > > On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane > wrote: > > > Hello team, > > During my exploration for documentation, I found the documentation > > link [1] on Roller home page [2] under the Documentation section. > > I see, currently, we are storing the documents in odt format. > > > > I would like to know the thoughts of the community on moving the > > documentation from .odt to .md > > > > We will have the following advantage if we use md format - > > > > 1. Rendering support of md file on GitHub > > The GitHub nicely render the md files, so if the files in md format, > > it will be easily rendered on GitHub. > > The odt files don't have any preview on GitHub and it forces the user > > to download to view the content. (This is annoying for the user and > > developers ;-) > > e.g. > > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt > > > > 2. Easy to maintain, the md standard is widely accepted > > The md format is widely used and this will open up the opportunity for > > new collaborators to participate. > > > > Kindly let me know if I am missing any information or history or > > purpose for maintaining our docs in .odt format. > > > > P.S. I see we are also maintaining the pdf version of odt [3] in master > > branch. > > The conversion from md to pdf is also doable. > > IMO, if we move our documents to md version, the pdf conversation will > > be no longer required since it will be rendered on GitHub properly. > > (Still, if I am missing anything, please feel free to comment :-) > > > > [1] https://github.com/apache/roller/tree/roller-5.2.0/docs > > [2] http://roller.apache.org/ > > [3] https://github.com/apache/roller/tree/master/docs > > > > Best regards, > > Swapnil M Mane, > > www.apache.org > >
Re: Roller Documentation from ODT to md (markdown)
+1 for AsciiDoc! I have a lot of experience with Asciidoctor, so let me know if you run into issues. Cheers, Matt > On Aug 27, 2019, at 11:06 AM, Swapnil M Mane wrote: > > Great, thanks Dave. > > Thoughts travels, while drafting the mail, AsciiDoc was also in my mind. > And AsciiDoc is also having all the advantages mentioned above. > > After some more exploration, I am now more inclined towards AsciiDoc. > So, +1 for AsciiDoc. > > > Best regards, > Swapnil M Mane, > www.apache.org > > On Tue, Aug 27, 2019 at 8:53 PM Dave wrote: >> >> I think that's a great idea and the docs, or a least the screenshots, need >> update for the new Roller 6 UI. Markdown is better for this in so many >> ways. AsciiDoc is also a good option but I don't have a strong preference >> on Markdown vs. AsciiDoc. >> >> Dave >> >> >> On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane >> wrote: >> >>> Hello team, >>> During my exploration for documentation, I found the documentation >>> link [1] on Roller home page [2] under the Documentation section. >>> I see, currently, we are storing the documents in odt format. >>> >>> I would like to know the thoughts of the community on moving the >>> documentation from .odt to .md >>> >>> We will have the following advantage if we use md format - >>> >>> 1. Rendering support of md file on GitHub >>> The GitHub nicely render the md files, so if the files in md format, >>> it will be easily rendered on GitHub. >>> The odt files don't have any preview on GitHub and it forces the user >>> to download to view the content. (This is annoying for the user and >>> developers ;-) >>> e.g. >>> https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt >>> >>> 2. Easy to maintain, the md standard is widely accepted >>> The md format is widely used and this will open up the opportunity for >>> new collaborators to participate. >>> >>> Kindly let me know if I am missing any information or history or >>> purpose for maintaining our docs in .odt format. >>> >>> P.S. I see we are also maintaining the pdf version of odt [3] in master >>> branch. >>> The conversion from md to pdf is also doable. >>> IMO, if we move our documents to md version, the pdf conversation will >>> be no longer required since it will be rendered on GitHub properly. >>> (Still, if I am missing anything, please feel free to comment :-) >>> >>> [1] https://github.com/apache/roller/tree/roller-5.2.0/docs >>> [2] http://roller.apache.org/ >>> [3] https://github.com/apache/roller/tree/master/docs >>> >>> Best regards, >>> Swapnil M Mane, >>> www.apache.org >>>
Re: Roller Documentation from ODT to md (markdown)
Sure Matt, thank you for the kind note. Will surely sync up with you in case of any issue. I also played with Asciidoctor in past, indeed a great tool! Best regards, Swapnil M Mane, www.apache.org On Tue, Aug 27, 2019 at 11:16 PM Matt Raible wrote: > > +1 for AsciiDoc! I have a lot of experience with Asciidoctor, so let me know > if you run into issues. > > Cheers, > > Matt > > > On Aug 27, 2019, at 11:06 AM, Swapnil M Mane > > wrote: > > > > Great, thanks Dave. > > > > Thoughts travels, while drafting the mail, AsciiDoc was also in my mind. > > And AsciiDoc is also having all the advantages mentioned above. > > > > After some more exploration, I am now more inclined towards AsciiDoc. > > So, +1 for AsciiDoc. > > > > > > Best regards, > > Swapnil M Mane, > > www.apache.org > > > > On Tue, Aug 27, 2019 at 8:53 PM Dave wrote: > >> > >> I think that's a great idea and the docs, or a least the screenshots, need > >> update for the new Roller 6 UI. Markdown is better for this in so many > >> ways. AsciiDoc is also a good option but I don't have a strong preference > >> on Markdown vs. AsciiDoc. > >> > >> Dave > >> > >> > >> On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane > >> wrote: > >> > >>> Hello team, > >>> During my exploration for documentation, I found the documentation > >>> link [1] on Roller home page [2] under the Documentation section. > >>> I see, currently, we are storing the documents in odt format. > >>> > >>> I would like to know the thoughts of the community on moving the > >>> documentation from .odt to .md > >>> > >>> We will have the following advantage if we use md format - > >>> > >>> 1. Rendering support of md file on GitHub > >>> The GitHub nicely render the md files, so if the files in md format, > >>> it will be easily rendered on GitHub. > >>> The odt files don't have any preview on GitHub and it forces the user > >>> to download to view the content. (This is annoying for the user and > >>> developers ;-) > >>> e.g. > >>> https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt > >>> > >>> 2. Easy to maintain, the md standard is widely accepted > >>> The md format is widely used and this will open up the opportunity for > >>> new collaborators to participate. > >>> > >>> Kindly let me know if I am missing any information or history or > >>> purpose for maintaining our docs in .odt format. > >>> > >>> P.S. I see we are also maintaining the pdf version of odt [3] in master > >>> branch. > >>> The conversion from md to pdf is also doable. > >>> IMO, if we move our documents to md version, the pdf conversation will > >>> be no longer required since it will be rendered on GitHub properly. > >>> (Still, if I am missing anything, please feel free to comment :-) > >>> > >>> [1] https://github.com/apache/roller/tree/roller-5.2.0/docs > >>> [2] http://roller.apache.org/ > >>> [3] https://github.com/apache/roller/tree/master/docs > >>> > >>> Best regards, > >>> Swapnil M Mane, > >>> www.apache.org > >>> >
