Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update sidebar to (dynamically) include all useful documentation #333

Open
OliverTod opened this issue Dec 15, 2020 · 6 comments
Open

Update sidebar to (dynamically) include all useful documentation #333

OliverTod opened this issue Dec 15, 2020 · 6 comments

Comments

@OliverTod
Copy link
Contributor

Issue:
The navigation sidebar on the Accord Project documentation website does not:

  • contain all relevant/useful content that has been produced over the years; or
  • dynamically update based on the content.

More detail:
There is a lot of good content in the broader Accord documentation that is not properly linked in the sidebar, but is still available through the search. From my review of the repository, most of it appears to be in one of several versioned document folders:
image

This suggests that the documents have deliberately not been included because they are out of date. Can someone who was involved in these recent documentation upgrades confirm this?

Proposed approach:

  1. review all of the 'versioned' documentation to classify each item as (1) useful as-is, (2) easy to update or (3) no longer relevant;
  2. manually update the navigation to include items in group (1);
    update and include items in group (2); and
  3. meanwhile, work on making the navigation be dynamically created by the content (this doesn't look like it's supported out of the box by docusaurus sidebar element, but shouldn't be too hard to do)
@OliverTod
Copy link
Contributor Author

Jolene, do you think you could allocate this issue to me? I will have a first crack at it.

@jolanglinais
Copy link
Member

Nice!

@dselman
Copy link
Contributor

dselman commented Dec 15, 2020

Please beware that versions are managed by Docusaurus scripts -- do not modify any of the versioned files. I believe @jeromesimeon did most of the content clean-up for Cicero 0.20.

@OliverTod
Copy link
Contributor Author

In terms of dynamically updating the sidebar: it looks like it could be achieved along these lines but I had a quick look at the other main users of docusaurus (eg React) and they aren't doing this.

I'm starting to think that this might be a feature that just gets in the way of docusaurus' versioning script - and the fix (manually updating the sidebars.json) is very straightforward.

@OliverTod
Copy link
Contributor Author

For the first part of this issue though (that is, making sure we haven't missed any good content in any of the documentation updates), I have identified the following as potentially useful content that doesn't seem to have made its way into the current version:
advanced-hyperledger.md
advanced-nodejs.md
spec-concepts.md
spec-example.md
spec-execution.md
spec-instance.md
spec-template.md
spec-packaging.md
example-eatapple.md
markup-blocks.md
markup-cicero.md
markup-ergo.md
markup-variables.md
ref-cicero-ui.md

I also noticed that the following pages are up, but somewhat incomplete:
tutorial-vscode.md - @dselman has an excellent video tutorial which ends promising further videos (which I can't find)
ref-glossary - the glossary only addresses a handful of terms

This is by no means a complete list - but maybe @jeromesimeon could let me know if i'm heading in a useful direction.

@jolanglinais
Copy link
Member

@OliverTod is there any update on this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants