958209 - Move RDP docs from wiki into toolkit/devtools/server/docs

Status: RESOLVED WONTFIX

(DevTools :: Debugger, task, P3)

Description

[Nick Fitzgerald [:fitzgen] [⏰PST; UTC-8]]

Moving the documentation in tree would make it so we could require documentation with patches to get an r+ and would make the documentation more up to date and valuable for readers.

If we want to maintain a wiki version, we could just dump it every release.

Question: What format should we use? HTML / Markdown / ReST & Sphinx?

Personally, I vote against using HTML directly. Markdown is nice to write/read, but can't do anchors. ReST is a little less nice to write/read but does anchors and I think we use sphinx elsewhere in m-c, so we might be able to hook into that as well.

Comment 1

[Eddy Bruel [:ejpbruel]]

My vote is for markdown, because it has the lowest barrier of entry. The biggest problem with our documentation is that we don't consistently update it, so making updating the docs as easy as possible should be our priority. If we actually did update our documentation consistently, the lack of anchors might be a bigger issue.

Jim, to my knowledge, you've done the most work on our documentation, so you should have a vote in this. What is your opinion?

Comment 2

[Jim Blandy :jimb]

I love markdown.

I've put together some machinery in js/src/doc for automatically formatting the Debugger API docs kept there and posting them to MDN. That uses Markdown.

I've managed to get some anchors into pandoc markdown, although I did have to resort to HTML.

Comment 3

[Eddy Bruel [:ejpbruel]]

That's two votes for markdown. Nick, can you live with that?

Comment 4

[Nick Fitzgerald [:fitzgen] [⏰PST; UTC-8]]

+1

Comment 5

[Alexandre Poirot [:ochameau]]

Could we proceed and land the docs? I'd like to finally contribute to it, especially about listTabs and new chrome debugging.
I imagine that's only about landing https://github.com/jimblandy/DebuggerDocs to m-c, while merging all pending pull requests before that?
Or does the docs are more up to date on the wiki, or somewhere else ? :-/

Comment 6

[Jim Blandy :jimb]

I didn't undertake the move because I wanted to get the scripts ready first. But... you know, there's just no reason the one needs the other. Let's just move it.

Comment 7

[Jim Blandy :jimb]

Also, the docs really should be split up into separate pages for the different actors.

BUT AGAIN, Jim, that's really not a prerequisite for the move. *ahem*

Comment 8

[Logan Smyth [:loganfsmyth]]

At this point, I'm not even sure which docs this is specifically referring to.