[Mesa-dev] [Request for Comments] - Port documentation to Markdown

[Eric Engestrom]

On Monday, 2017-03-06 18:36:32 +0000, Jean Hertel wrote:
> Hello guys,
> 
> 
> I want to propose a port of the current HTML documentation to a markdown-like syntax.
> 

I was thinking of doing essentially the same thing, just haven't had the
time to do so yet. Please CC me (eric at engestrom.ch) on anything related
to this project :)

> 
> Current problems
> 
> 
> Right now I see some problems with the approach used.
> 
>   *   People maintaining the documentation must know basic HTML syntax;
>   *   There is no easy way to add a new release page;
>      *   You need to open the index file and make changes there;
>      *   You need to make a new file that will say what has been changed;
>      *   You need to remember to update the release notes pages;
>   *   The current website has many HTML tags not being closed;
>   *   The website don't fit well in mobile area. (The layout is not responsive);
>   *   Making any change to the layout is very hard, because you need to rewrite many pages;
>   *   The current website doesn't show all the possibilities of the library. The website has a 1990 layout, and I think having a new layout would benefit the project;

Agreed on all counts :)

> 
> Proposal for Markdown
> 
> Rewriting the documentation in a markdown syntax can bring some benefits to the development, like:
> 
>   *   Anyone writing for freedesktop.org, StackOverflow and Github already knows the markdown syntax.
>   *   Independence of HTML. The developer don't need to worry if the HTML output will be correct. The generator makes all the translation from markdown to HTML;

Agreed, but more on this below.

>   *   Easily change the layout of the site, simply changing the theme; (I don't think you change the layout much, but allowing it to be easy wont hurt)

Having a proper (generated?) HTML structure and a clean CSS is all you
need for this.

>   *   Creating a new release post can be maded easy, using some static site generator, for example, pelican;

This can be done with any old tool. You could even have a simple
release.template and copy it and modify it as you need to make a new
release.

> 
> 
> Right now I have maded a partial port from HTML to Markdown.
> 
> The code can be found here: https://github.com/jlHertel/mesa-pelican

I looked at your conversion on a couple random files, and it looks
pretty good to me. (I have a couple nit-picks obviously :P, but the
basic concept is fine.)

> 
> I'm using the pelican static site generator with a layout ported from Wordpress using Twitter Bootstrap CSS.
> 
> A live preview can be found here: http://mesa.jeanhertel.com.br/
> 
> 
> The static site generator tool and the theme used can be ignored if you want, the point here is to rewrite the documentation in a way that is easy to maintain and that don't need a good knowledge in HTML.

I haven't look into Pelican (and won't have time to do so before the
weekend), but I think it sounds like a reasonable kind of requirement to
have. There are plenty of other markdown-to-html generators around, if
someone prefers another one.

One thing that I would prefer so not see if heavy things like Bootstrap.
We definitely don't need it, I think writing our own few lines of CSS
(which can be inspired by anything you want) is better. We have more
than enough people who know how to do it (myself included), it will be
cleaner (we won't need to include the whole forest to get our tree) and
much easier to fix when there's a bug.

One core thing that might need to be changed is Markdown itself. It is
great for prose, but it breaks down quite quickly when you start to
write code in it. For this reason, people are moving to RST instead for
code documentation.

The question becomes: how much code do we expect to put on the website,
and how complex will it be?

I had in mind that we could start adding small code examples to help new
learners to understand how the apis are used. No tutorial-style articles,
just enough to understand that "you need to init this, then query that,
and pass arguments like this, and handle errors like that".

If we ever need to convert from Markdown to RST, I think the conversion
would be pretty trivial, so baring objections I'd recommend going with
Markdown for now.

I'll have a look at generators and make sure things can work on
annarchy when I find the time, and I'll get back to you.

Cheers,
  Eric


> 
> 
> Please leave your comments on the proposal.
> 
> 
> Best Regards
> 
> Jean Hertel
> 
> 
> ------------------
> 
> Some terms used are web-focused, so I will leave some links if anyone don't know what I mean:
> 
> Twitter Bootstrap Css: http://getbootstrap.com/
> 
> Responsive layout: https://en.wikipedia.org/wiki/Responsive_web_design
> 
> Pelican static site generator: https://blog.getpelican.com/
> 
> Markdown: https://en.wikipedia.org/wiki/Markdown