Hello guys,
I want to propose a port of the current HTML documentation to a markdown-like
syntax.
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;
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;
* 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)
* Creating a new release post can be maded easy, using some static site
generator, for example, pelican;
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'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.
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
_______________________________________________
mesa-dev mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/mesa-dev
