Design site content and navigation

[msgilligan]

• What content should be on this page?
• What should the Navigation look like?

[msgilligan]

@genevievePrima can you help?

[msgilligan]

I made some progress on this today. As of 6f9d3d7 the following is done and visible on the under construction site:

• Basic outline of menu structure
• Some pages are placeholders for content
• Some menus link to "WIX" site content that needs to be moved
• Direct links to Spec and Whitepaper pages on the site (Yes, I think we should recreate a true Whitepaper with higher level description of Omni.)

What needs to be done:

• Logos, graphic design, etc.
• Create content for placeholder pages
• Move content from existing (WIX) site.
• Create a new white paper
• Fix formatting of Spec, add images, automatically pull for spec repo.
• Create CNAME record to forward www.omnilayer.org to Github

[dexX7]

This is awesome! What I'd also like to see:

• historical changelogs of Omni Core
• a page for historical/active alerts and feature activations
• potentially other documents

I totally suck at webdesign, and I'm also not familiar with page generation (but love to learn more), so what can I do to make it more easy to integrate?

We started with src/omnicore/doc to consolidate docs, and at some point I'd also like to include process definitions, and ideally more information for developers, though this is probably still a long way.

Here is a very loose collection, of what I had in mind (all this is probably not usable in this context, but just to give you an idea):

Guides:

• MetaDEx testing guide
• Token based 2-of-3 multisig arbitration with Omni Core (incomplete, not yet fully implemented)

Process:

• Contributing to Omni Core (incomplete)
• Signing of Omni Core build results via Gitian
• Steps to release Omni Core (incomplete)
• Steps to create a new checkpoint (incomplete)

Developer notes:

• Omni Core API documentation
• Omni Core configuration (incomplete, see Documentation for Omni Core specific options omnicore#71)
• Events and signals in Omni Core (outdated, incomplete)
• Data persistence in Omni Core (outdated, incomplete)

Yes, I think we should recreate a true Whitepaper with higher level description of Omni

ACK!

[msgilligan]

I'm also not familiar with page generation (but love to learn more), so what can I do to make it more easy to integrate?

The tool that we are using JBake supports both Github markdown and AsciiDoctor syntax content files. So it should be relatively easy to pull in content from the OmniCore repository. (I'm not sure the best mechanism for access the files, perhaps a Git submodule, though maybe there is a better way) AsciiDoctor format is much better suited for producing specifications, reference manuals, software documentation especially when in a longer format needing a table of contents, code examples, etc. AsciiDoctor also has support for including files. For example, the Bitcoin Book is written in AsciiDoctor.

I would recommend using AsciiDoctor for any major documents on the OmniCore project and possibly converting a few of the existing documents.

The build for this site is using the JBake Gradle Plugin so you can play around with the site by checking out the source branch and then doing a ./gradlew to build the site. The output will be in ./build/jbake/index.html These instructions are in the README, of course.

[dexX7]

Thanks for the information, I'm going to look into it!

I'm not sure the best mechanism for access the files, perhaps a Git submodule, though maybe there is a better way

I started with contribution guidelines for Omni Core (see OmniLayer/omnicore#186; help welcomed, so far it's a little bit more than a loose collection of keywords), and I saw there is also a currently blank page for contributions in this repo.

Aside from whether the document is intended to be more general, or Omni Core specific, just for my understanding: to cross-reference/cross-include documents, Omni Core would be added here as submodule, so there is direct access to the files, right? This actually makes me wonder, whether we may create a new repo for documentation of any kind, and then refer to it from the actual projects. On the other hand, the Omni Core docs are embedded into the build process, and ultimately packed into the setup/installer etc.. I'm not sure, how/if that combination would play well together.

[msgilligan]

It might make sense to make this repo (omnilayer.github.io) the documentation project and put most of the documentation in this repo. Except documentation that is closely bound to the source, etc. In fact, I'm considering having this repository replace (or merge with) the spec repository. (There are couple of different ways that could be done preserving existing links)

I'm not sure what the best mechanism for handling documentation between multiple repositories is. There are a few possible approaches:

1. Include project repositories as Git submodules
2. Other Git-based multi-repo solutions
3. Include content from a URL
4. Build sub-document sets as .zip files, release as binaries and the pull into parent documentation project
5. Other

Whichever of the above does the job in the simplest and most-reliable manner would be best.

[msgilligan]

@dexX7 : I sent you a (proof of concept) PR converting your CONTRIBUTING.md document to CONTRIBUTING.adoc

dexX7/bitcoin#2

[msgilligan]

... and I dropped in your version to contributing.adoc and published to this site.

UPDATE: I also replaced the ascii-art flow chart with GraphViz one that renders to SVG. I did this over in OmniJ because I have diagrams configured to work with the raw Gradle AsciiDoctor plugin. I'll try configure them with Gradle JBake plugin for use on the Github Pages site soon.

[dexX7]

UPDATE: I also replaced the ascii-art flow chart with GraphViz one that renders to SVG.

This is fascinating! I mean, we can argue about details of the styling etc. (the color red indicates errors, danger, ...), but the difference between:

• the markdown draft
• nearly the same draft as html

... is impressive, and I really like where this is going. Do you want to take over the original submission? There isn't much I can add from this point on, and we basically need a) better phrasings/text, b) fill in all blanks, c) finally style it, in one way or another.

We still have to consider that some content is also shown on GitHub directly, like this doc, and unprocessed (i.e. on GH) the pull request lifecyle is unfortunally not really usable.

Given that graphs and charts are very useful, likely also for the specification at some point later, ideally we'd find a solution that works both ways. Or do you think it would be better to move to html completely? I personally find it more appealing, if I can see the docs on GitHub, too, because websites are often filled with other stuff, and distracting. Maybe that's just me, though.

[msgilligan]

Github does render .adoc files, even the TOC: https://github.com/OmniLayer/OmniJ/blob/7260ecbf1a1d057cbe505e3f0b2d37b02c52a00a/adoc/contributing.adoc (It doesn't know how to render the diagram, though.) You can even click the pencil icon and edit on the server, with AsciiDoc markdown syntax highlighting!

@dexX7 Did you see the PR I sent you to convert CONTRIBUTING from .md to .adoc format?

The version rendered by the Gradle AsciiDoctor Plugin uses the default AsciiDoctor stylesheet. The version rendered by the Gradle JBake Plugin uses the default JBake stylesheets (which uses Bootstrap.) I'm hoping (Issue #3) that we'll create a custom Omni stylesheet for the site. Changing the colors should be easy enough.

[dexX7]

It doesn't know how to render the diagram, though.

In this context I was referring to the diagram.

The other outstanding challenge I currently see is how we're going to deal with documentation, which is packed into setup/installer files.

However, instead of simply adding plain text files (as done right now), it would be much better, if we could ship it with a styled documentation, and I wouldn't be surprised, if we can manage to integrate the page generation into the build/make process. Once I find some time, I'm going to look into it. You provided quite a few references, which is a great starting point for me.

[msgilligan]

@dexX7 if you and @zathras-crypto are willing to learn and use AsciiDoctor markdown, and you are willing to help with some of the build issues. I'm willing to help get the Omni Core documentation structured nicely. As you know, it is something I have some experience with and enjoy doing.

Is there a parent/tracking issue in Omni Core we could use to discuss this?

[msgilligan]

4. Build sub-document sets as .zip files, release as binaries and the pull into parent documentation project

I'm leaning towards this solution as I've seen it used successfully in other projects. We will almost certainly want to publish documentation for at least two versions of the software. If we can build .zip files of Doxygen docs and everything tied closely to the source code as part of the build process we can import them and publish them on the documentation site. We can also do some/most styling/templating in/on the documentation project/site.

[dexX7]

I support the idea.

We have OmniLayer/omnicore#185 open for the contributing doc, but feel free to open a more general issue.