[Juju-gui-peeps] I WANT YOU, to give me your feedback (Juju docs!)

[Joshua Strobl]

I would still prefer Markdown over Restructured Text. Hyperlinking in 
Markdown is much more simplistic, list items aren't as flexible in 
Markdown (which in the end makes things more readable since you can find 
predicable characters in which list items would be indicated as), Field 
and Bibliographic specific syntax is hardly necessary when it comes to 
technical documentation (even for wikis it'd be difficult to argue the 
use of Restructured Text), Restructured Text doesn't treat indentation 
as code blocks until it's paired with ::, which is unnecessary and just 
means that it'd be more difficult to scan the text (imagine, you'd 
probably need to CTRL+F and type :: and search for any code syntax, on 
top of fiddling with indentation), Doctest blocks aren't really 
necessary when there is already existing syntax for code, auto-numbered 
and auto-symbol footnotes aren't necessary in the syntax language), etc.

I think we need something simple, clean, easy to quickly scan through, 
has readily available online and offline editors (free and open source 
or paid, doesn't matter - might I note I'm not claiming Restructured 
Text doesn't have equivalent software, I've just noticed through my own 
observations that Markdown editors are more common and the syntax as a 
whole is more widely accepted.)

I vote against using HTML5/CSS/custom scripts, even as a web developer 
myself. The barrier of entry to documentation editing should be as low 
as possible (well, no plain-text with a lack of structure please =P).

- Joshua

On 3/21/2014 20:07, Kapil Thangavelu wrote:
> This is pretty biased towards markdown, generally restructured text 
> has a tradition and success for being used for documentation.. Any 
> plain text format is big win imo from what we have today.
> http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext
>
> So the question becomes, what format would be preferential among 
> developers for writing docs . The candidates so far are as follows
>
>   1. Markdown
>   2. Restructured Text
>   3. HTML5/CSS preprocessors/custom scripts (Currently in use)
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju/attachments/20140321/32928dc4/attachment-0001.html>