Move documentation of options to a table

[sboekhoff]

The documentation style guide postulates using lists when documenting methods and their options. Especially for long list this can be confusing (see e.g. https://github.com/electron/electron/blob/master/docs/api/browser-window.md#new-browserwindowoptions)

In order to ease the grasping of information, I'd like to propose using tables instead of lists.

Currently the documentation for the constructor of BrowserWindow looks like this:

Using a table makes it much easier to find data-types, default values, etc.

[MarshallOfSound]

/cc @zeke

Assuming this would break the docs linting and the conversion to yml for the documentation site

[sboekhoff]

@MarshallOfSound @zeke How can if something breaks? I ran:

npm install
npm run-script lint-docs
npm run-script lint-js

which did not give any exception.

If you're fine with using tables, I would start with converting other parts of the docs.

[MarshallOfSound]

If you're fine with using tables, I would start with converting other parts of the docs.

I can't make that call. It's something @zeke will probably have a say on

[zeke]

I'm on the fence. I kind of like the tables because they're a bit easier to read when formatted, but it also means a lot more work (and increased likelihood of formatting errors) for the author. Markdown tables are not very fun to write.

@MarshallOfSound is referring to #6408 and electron-docs-linter, a work-in-progress to parse all the API docs into a structured data object. Using tables would not be a blocker for that, it would just need to be revised to parse tables instead of lists.

I would prefer to put this on hold until we ship #6408, then start experimenting with alternative (and hopefully better!) ways of displaying the API docs on electron.atom.io.

[sboekhoff]

... it also means a lot more work (and increased likelihood of formatting errors) for the author. Markdown tables are not very fun to write.

I think it depends on your own preferences - I prefer working with tables. Especially in Markdown (and even more in Asciidoc) sources it increases readability.

I would prefer to put this on hold ...

@zeke: Just let me know ...; I'm willing to invest time to reformat the lists to tables.

[enlight]

When this PR was first submitted I was all 👍 on this, but having spent some time recently fighting a table in a markdown document I have changed my opinion to 👎👎👎. Basically, your standard markdown table syntax doesn't allow line breaks within a cell, so you end up with these crazy long lines with embedded <br> tags (to force line breaks), so readability plummets. Then you realize you can embed an HTML <table> in the document so you can have (a somewhat, but not really) more readable document, only to discover that GitHub will throw your inline styles into the gutter and render your table however it pleases. Finally, you end up using deprecated HTML 4 attributes to force proper alignment of cell content. Victory at last! But was it worth it? Not really.

[sboekhoff]

@enlight : Your are talking about shortcomings in the syntax of Markdown. I totally agree with you that defining tables in Markdown can be painful. That's why I prefer AsciiDoc(tor) http://asciidoctor.org/.

The point of this PR was not to promote "tables using AsciiDoc" but to make the output of the documentation more readable for the user (who is typically not interested in how this goal is achieved).

Unfortunately the electron documentation is written in Markdown (and not in e.g. Asciidoc).

So maybe your opinion is 👍 tables and 👎 Markdown.

I think shortcoming of the technologies used to create the documentation should not influence the quality of the documentation.

[zeke]

markdown table syntax doesn't allow line breaks within a cell, so you end up with these crazy long lines

I tend to agree with this sentiment. We have to consider that developers are consuming this documentation in a variety of ways. Some of them include:

• https://github.com/electron/electron/docs
• http://electron.atom.io/docs
• Right inside the $EDITOR

#7120 shipped recently, and the next release of Electron (1.4.1) will include an electron-api.json file that describes all the APIs. I think a better way to reach tabular utopia would be to use this new structured data to render dynamic templates on electron.atom.io (or elsewhere). This will allow us a lot more flexibility in how we render and style the docs.

Not seeing a lot of strong reactions either way from people here, so I'm going to close this out in favor of that approach.