Expand docs index into a comprehensive table of contents (Part 1: User Docs) #60
Conversation
This docinfo file is empty to avoid adding the "Back to index" link found in the default `docinfo-footer.html` file. See https://asciidoctor.org/docs/user-manual/#naming-docinfo-files for details on how all this works.
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.
|
To prevent any duplication and synchronization errors, will we link from the existing FAQ page more and more to the content created on docs.bisq.network (e.g. https://bisq.network/faq/#altcoins)? |
|
Glad you asked, @ripcurlx. Where a doc doesn't exist yet, and there is something on the website we can link to, we can do that. For example, I would add a link to bisq.network/faq/#altcoins from the word This is all just stopgap stuff, though. The idea is to write an actual Zooming out a bit, I believe the FAQ should simply go away. You'll notice there's no entry for it in the new "User Docs" section of the index, and that is quite intentional. FAQs are often great, especially in the early days of a project, but they can also easily become a kind of "cheap" way out of organizing your project's information in a way that's actually intuitive and helpful. I don't want to make people read through a big list of mostly unstructured questions-and-answers to find what they need. I want to present it to them in a way that's intentionally designed to be pleasant and helpful and appropriate at every step of the way. So you can think of what's happening here in this PR as systematically gutting the FAQ (and many other pages on the current website), transforming them into a well-organized collection of documents that anyone can navigate through get to what they need. As this process progresses, there will be less and less 'content' on the main site, and this too is intentional. I'd like to see the main bisq.network site become a very simple "brochure" for Bisq; a simple and attractive few pages that show the user what Bisq is and why they should care in an emotionally compelling way, such that they follow the key call to action, which is to Get Started. Upon clicking that link, they find themselves in Bisq docs-land, where they can then find everything they need. I believe this approach is well-aligned with @pedromvpg's proposed changes to the website in his design refresh proposal. How does that sound? |
|
Just to make it a bit easier to see what's being discussed, here's a screenshot of the latest deploy preview, from https://deploy-preview-60--bisq-docs.netlify.com:
|
See bisq-network/bisq-docs#60, where these new redirects are used.
As as stopgap measure until proper docs are written. See bisq-network#60 (comment) for context.
Like the previous commit, this is a stopgap measure until a proper doc is written to capture these resources.
cbeams
changed the title
|
I've removed the [WIP] status from this pull request, have added a few additional links, and am going to merge it as-is now, in order to get the changes that have already been made to the overall structure, and especially the "User Docs" section of the ToC out there for people. I'll follow up with another pull request afterward that will focus on building out the "Contributor Docs" section of the ToC. @ripcurlx, note that I did add links to the FAQ as discussed in 193942c, thanks. |
Expand docs index into a comprehensive table of contents
cbeams
changed the title
@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:
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, 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.