One related question: *where* should they all go? For kernel docs, we could possibly use the kernel 'master' branch (or a new 'docs' branch?), since it's basically abandoned. General 'developer guide' could likely go in the main chromiumos/docs/ directory?

for the kernel, there's a chromeos/ subdir where you could put many docs.  especially ones that basically document how to use the scripts/ and config/ dirs.  there's the issue of the docs being branched, but on the flip side, it means the docs would match the local config/script files which themselves are already branched.

if putting the docs in the relevant project repo itself doesn't work, then use the common docs/ repo.  that's where we put all such things already.

> there's the issue of the docs being branched,

Yes, I wouldn't like to have to artificially manage updating N branches of the kernel docs for 5+ years.

> but on the flip side, it means the docs would match the local config/script files which themselves are already branched.

That's just about the only upside I can think of. I'd expect 99% of our kernel docs should be relevant to any kernel branch.

> if putting the docs in the relevant project repo itself doesn't work, then use the common docs/ repo.  that's where we put all such things already.

Maybe that's good enough. And maybe a kernel subdirectory if really needed.

I'm OK with this idea and it does seem like it will help with allowing more people to update the docs.  IIRC the Wiki UI was fairly annoying for large docs and it's also not very multi-user friendly.

Right.  Definitely not N copies.  Putting somewhere common seems fine to me.

I have a preference for keeping docs as close as possible to code, but the branching argument against doing this for kernel docs seems compelling. Putting a kernel/ subdirectory in the docs repo probably makes sense since multiple files are expected.

> (I've been told we might even get a lot more donated documentation that way.)

Quoting myself from this 2015/2016 (and recommended) discussion on the same topic:
https://groups.google.com/a/chromium.org/d/msg/chromium-os-dev/k40tGJhnzC4/JuwkHEboAQAJ

> Part of our internal documentation (wiki) is specific to either our lab or infrastructure or hardware,... generally of no interest to anyone but us. The rest on the other hand is either amending or extending (or duplicating...) the public guides. While the extra effort caused by this split is relatively small for us, the inability to submit new or updated documentation is a bigger loss for the Chrome OS project and community.

Let me add now: just like open-source code, open-source documentation is more rewarding than updating an obscure team wiki because it gives contributors better visibility and recognition; sometimes even from their own management :-)

Moving the kernel docs to docs repo under kernel directory SGTM.  We should put a pointer from dev.chromium.org to that post-move.

The following revision refers to this bug:
  https://chromium.googlesource.com/chromiumos/docs/+/1dd96523846992effc9d255f41e94b146f3eab95

commit 1dd96523846992effc9d255f41e94b146f3eab95
Author: Brian Norris <briannorris@chromium.org>
Date: Fri Aug 31 18:29:37 2018

kernel_faq: convert to markdown

Pulled from:

https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/kernel-faq

with Turndown:

http://domchristie.github.io/turndown/

Minimal edits: trim whitespace and wrap lines

BUG=chromium:813194
TEST=md_browser / gitlies

Change-Id: I2bc04c53fecbfe154837c520ac5d9457a1304159
Signed-off-by: Brian Norris <briannorris@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1199963

[add] https://crrev.com/1dd96523846992effc9d255f41e94b146f3eab95/kernel_faq.md

The following revision refers to this bug:
  https://chromium.googlesource.com/chromiumos/docs/+/4606b700fbb612f46cf0936d0aee7f57cfe621aa

commit 4606b700fbb612f46cf0936d0aee7f57cfe621aa
Author: Brian Norris <briannorris@chromium.org>
Date: Fri Aug 31 18:29:49 2018

kernel_faq: fixup markdown

A reasonable first pass:

 * full code blocks instead of inline code snippets
 * merge multiline code blocks that didn't get auto-formatted
 * swap bold for code font in some places
 * re-introduce code whitespace that was lost

Done with a variety of vim macros to look for repeated patterns.

BUG=chromium:813194
TEST=md_browser / gitlies

Change-Id: I8e2092af8c3fcfc047f03beee8e214331fd2bf2b
Signed-off-by: Brian Norris <briannorris@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1199964

[modify] https://crrev.com/4606b700fbb612f46cf0936d0aee7f57cfe621aa/kernel_faq.md

Somebody else already moved the Developer Guide. I just added kernel_faq.md:

https://chromium.googlesource.com/chromiumos/docs/+/master/kernel_faq.md

If you're interested, compare soon, as I'm going to stub this out today:

https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/kernel-faq

chromium.org members can view the history there, but I'm not sure about external folks.