Closed Bug 958209 Opened 9 years ago Closed 2 years ago

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

Categories

(DevTools :: Debugger, task, P3)

x86
macOS
task

Tracking

(Not tracked)

RESOLVED WONTFIX

People

(Reporter: fitzgen, Unassigned)

References

(Blocks 1 open bug)

Details

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.
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?
Flags: needinfo?(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.
Flags: needinfo?(jimb)
That's two votes for markdown. Nick, can you live with that?
Flags: needinfo?(nfitzgerald)
+1
Flags: needinfo?(nfitzgerald)
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 ? :-/
Flags: needinfo?(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.
Flags: needinfo?(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*
Severity: normal → enhancement
Product: Firefox → DevTools
Blocks: dbg-server
Type: enhancement → task

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

Status: NEW → RESOLVED
Closed: 2 years ago
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.