Move documentation to wiki

[dlech]

We are getting so many features, I'm thinking it would be better to turn on the wiki here rather than trying to cram everything into the readme. Thoughts?

GitHub Pages or ReadTheDocs are possibilities too.

[cmacq2]

May be worth it. I'd avoid making it complex: there are not all that many technical topics we really need to address:

• Usage
  • Command types (subsection on brickstrap.conf ??)
  • Layout of destdir:
  • Files/dirs generated by brickstrap
  • Subsection on destdir/rootfs.
  • Components: what they are, how they work. (End user perspective).
• Default/example projects.
• Setting up a project:
  • Components: what they are, how they work. (Developer perspective).
  • Various file types
  • Notably: hooks. Reminder: components. Reminder: prefer packaging over hooks. Hint: namespacing.
  • Notably: package files. Reminder: need for granular files, also: blacklisting files/packages. Reminder: components.
  • Notably: config. Reminder: namespacing.
  • Notably: multistrap.conf. Reminder: use packages/repos instead of hooks. Hint: namespacing.
  • custom-report.sh
  • custom-image.sh (if applicable)
  • Reminder: write docs for your end users.
• Namespacing (for people looking to contribute to brickstrap)
• Architecture: cross building, QEMU, binfmt, and ARCH variable.
• Rootfs layout:
  • Default layouts.
  • Custom layout: how to add your own driver, guestfish. Reminder: components. Hint: namespacing.

---

Further thoughts:

The current brickstrap code already reserves a docs/ subtree for this purpose (it forbids -p docs or equivalent). Instead of a single monolithic readme we should probably have multiple markdown files dedicated to separate topics and then simply cross reference them from the (top level) readme.

That also goes someway to the TL;DR effect a long readme might have on new users.

Related: it might be wortwhile to investigate using something like pandoc to convert these *.md files into manpages.

[dlech]

I was actually thinking the same thing about using markdown in the git tree so that it is readable on GitHub and using something to convert it to man pages that can be included in the debian package. I had a look at pandoc and it looks like a good choice for this. FYI, I've moved the project definition (there is only one now) to a projects/ subfolder, so the check for docs on -p is probably no longer necessary.

[dlech]

pandoc is the winner