search

hyperledger / caliper

A blockchain benchmark framework to measure performance of multiple blockchain solutions https://wiki.hyperledger.org/display/caliper
https://hyperledger.github.io/caliper/
Apache License 2.0
650 stars 402 forks source link

Improve Caliper documentation #507

Open aklenik opened 5 years ago

aklenik commented 5 years ago

Context

This is a general issue relating to the current state of the documentation. Before Caliper is published to npm (thus increasing its usability and making it more widespread hopefully), the documentation must also be improved in several areas (prompted by #506).

Tasks

I've gathered the following tasks so far relating to improving the documentation. These can be refined after further discussions.

  1. [ ] Consolidate the structure/outline (categories, [new] pages, order, etc)
  2. [ ] Move and rewrite current content as needed (some pages are really packed right now)
  3. [ ] Fill the empty placeholder pages with new content (mainly tutorials, Q&A, etc)
  4. [ ] Eliminate typos
jeffywu commented 5 years ago

Hi, happy to help with the documentation. Is there any appetite for merging the gh_pages branch into master and putting it into a /doc folder on the master branch? This would save having to create two PRs when adding a feature and improving the documentation. Also the benefit of being able to pull the docs down locally with one fetch. https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages

You can configure GitHub Pages to publish your site's source files from master, gh-pages, or a /docs folder on your master branch for Project Pages and other Pages sites that meet certain criteria.

aklenik commented 5 years ago

@jeffywu Every help is welcome! It's always useful to get yet another perspective on the documentation. The core developers might be a bit biased about what's trivial and what needs additional explanation, so we're glad for every feedback.

The docs dir was the original approach, but it was hard to navigate, and a little hard to maintain. Having a separate branch makes it easier to separate the code from the docs (both for reviews, and updates).

(A personal experience: it always bothered me that I can't clearly follow only the docs changes in fabric, for example. With a separate doc-only branch, it's easier to re-read the changed part of the docs)

jeffywu commented 5 years ago

Is there a part of the docs that you think need the most work right now?

aklenik commented 5 years ago

In the architecture page, there are a few things that could be separated. For example, I'd give its own page to the following topics:

And the everlasting battle against typos of course :D