[bisq-network/bisq-docs] [WIP] Expand docs index into a comprehensive table of contents (#60)

[Chris Beams]

@bisq-network/contributors, have a look at the Netlify deploy preview for this PR (you can find it in the "Checks" section below). In it, you'll see the main page of https://docs.bisq.network expanding to become an easy to use, comprehensive table of contents for all things Bisq.

It's broken down into major sections by audience, e.g. "User Docs" and "Contributor Docs", and from there, further broken down according to what these audiences are likely to need to know first, such as the "Essentials" that cover what Bisq is, how to get started trading, and so on.

Some of docs you see mentioned on the page don't exist yet. From the comment on commit 2f90e71:

> As explained in the new admonition at the top of the page, many of these
> docs have not yet been written, and therefore have no links. The idea is to
> publish this list of the docs we have _and_ the docs we want to have, such
> that users can get a sense of everything we want them to know about Bisq,
> even though it's not all ready to go yet, and such that contributors can
> get a sense of where they can add value by writing these incomplete docs.
>
> In subsequent commits, the same kind of 'fleshing out' will be done for the
> 'Contributor Docs' section of the index page.

There are certainly more as-yet-unwritten docs that could be called out here, but I find the current mix to be a good balance. Do feel free, however, to add comments about or submit pull requests for additional docs you think should be written.


An aside about the future of these docs
--------

As this new documentation approach progresses, my goal is to get to a place where we have a truly _documentation-driven_ approach to developing new Bisq software. Today, we write proposals for new ideas, and that's a great way to get initial validation whether a new component or major change to an existing component is a good idea in the first place. In the future, I'd like to develop a culture in which the first thing we do after a proposal, or possibly in conjunction with a proposal, is write the high-level documentation for the change being proposed. Going back to our recent definition of [delivered work](https://github.com/bisq-network/proposals/issues/19), if something is not documented, it effectively does not exist. I'd like to take this one step further now, and create a condition in which we write that documentation _before_ doing any substantive work, such that we are always operating from the _user's perspective_ in everything we do. Writing user documentation first is a tried-and-true approach to aligning on what matters most, to minimizing bikeshedding, and ultimately to making sure that we create valuable software that people actually want. Amazon has famously followed this approach, which they call "Working Backwards". I recommend reading AWS CTO Werner Vogels' blog post on the matter here: https://www.allthingsdistributed.com/2006/11/working_backwards.html.
You can view, comment on, or merge this pull request online at:

  https://github.com/bisq-network/bisq-docs/pull/60

-- Commit Summary --

  * Restructure from bullets to 2nd-level headings
  * Refine GitHub-related contributor checklist items
  * Add ToC to intro doc for navigational consistency
  * Add private docinfo file for index page
  * Add ToC to contributor-checklist for nav consistency
  * Flesh out 'User Docs' section of index page

-- File Changes --

    M contributor-checklist.adoc (8)
    A index-docinfo-footer.html (0)
    M index.adoc (82)
    M intro.adoc (1)

-- Patch Links --

https://github.com/bisq-network/bisq-docs/pull/60.patch
https://github.com/bisq-network/bisq-docs/pull/60.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq-docs/pull/60
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/github/attachments/20180530/804585d2/attachment-0001.html>