Hiero Docs Discussion

[Reccetech]

In our last TSC Meeting (6/17) we agreed to discuss Hiero Docs in our next TSC meeting (6/24). This post is to lays out some groundwork for that discussion.

Just to baseline Hiero currently has docs at docs.hiero.org. This is based on the Gitbooks framework which is used by the Hashgraph team for docs.hedera.com. In additional LFDT provides docs guidelines here and they recommend to use an MKDocs template here.

So a debate has come up on what docs approach Hiero should take:
Approach1: Individual Hiero project maintainers should be able to build out docs for their repo as they see fit, using whatever docs framework they wish. The only limitation should be the use of some baseline brand assets. This gives developers the freedom to choose docs frameworks that fit their own preferences, and enable features like automation and integrations.

Approach2: This approach takes the viewpoint that Consumers of docs within a LF single project (like Hiero) appreciate consistency between docs. This consistency can include:

1. A single place to view all docs
2. Navigation and layout consistency between docs
3. Visual consistency between docs.
4. Consistency in language and terms between docs

So if we want this consistency then TSC needs to set out docs guidelines and requirements for all projects.

Approach3: A hybrid between Approach 1 and 2, is that each repo can do their own docs but they must use the same docs framework and template like what is suggested by LFDT above.

So looking across LF projects we can see examples of both Approaches in real life.
Approach1: In the Kubernetes project each repo has their own docs framework, look&feel etc.. The Kubernetes docs here, the kOps docs here, the minikube docs here
Approach2: In the Pytorch project we see an example where across all their 82 repos their documentation can be found here

So the discussion is about what Approach does Hiero want to take for docs across the projects?
@may-hashpack

[jwagantall]

Thank you so much for putting this together @Reccetech !

I think it can help our decision to also define our ultimate goal. For instance:

We want to make sure that the approach we select helps:

• Make it easier for brand new contributors to get them started faster.
• Makes it easier for the docs team to maintain/review new content.
• Branding and style looks consistent.
• Is simple, easy to use for new members.

Target goals like this one can help us setting up a score to each one of the approaches and help us decide better.

Thank you!

[hendrikebbers]

@Reccetech my suggestion would be:

We offer docs.hiero.org as global doc page on that every project can get a section and contribute to it. Using GitBooks has many advantages against MKDocs as far as I know. Therefore I would like to stay on GitBooks. That should be the best practice and suggested place to add documentation

If a project does not want to use it, a different way of providing documentation can be done by the project. Here, it is important that it is open and easy to use and extend. Next to that hiero branding guidelines (once we have defined them) must be fulfilled. If a project decides to go this way, we will add an external link to that documentation in the global docs.hiero.org page

[rbarker-dev]

Here, it is important that it is open and easy to use and extend. Next to that hiero branding guidelines (once we have defined them) must be fulfilled. If a project decides to go this way, we will add an external link to that documentation in the global docs.hiero.org page

I like this. It's in line with Approach 1 as well.

[SimiHunjan]

I like option 1, where Hiero can recommend using docs.hiero.org for documentation, but individual project maintainers still have the flexibility to host their own documentation if they choose.

Hiero can provide brand guideline (logo usage, fonts, colors, etc) that apply consistently whether the documentation is published on the central Hiero site or maintained independently.

[rbarker-dev]

I really think it's important that project maintainers have as much autonomy over their projects as possible. As such with respect to the options above (given those are the only approaches?)

• Approach-1 seems to me to be the most favorable.

This provides maintainers with the ability to use their own documentation expertise, encourages maintainers to align documentation with the Hiero brand using a brand-kit/assets made available by hiero, and keeps documentation maintenance in with the specific project.

• Approach 2 feels unfavorable to me as it takes the onus to documentation out of the project maintainers hands and places it at higher level. The way I interpret this is that a documentation group will have oversight on all documentation efforts within the org. That's not set up yet and probably doesn't need to be.

• Approach 3 feels extremely unfavorable to me as I don't think we should mandate any frameworks for documentation.

[nathanklick]

As a maintainer of the hiero-ledger/solo project, the only viable approach, in my opinion, is Approach 1. The Solo project currently provides our users with standardized, versioned, and automatically generated documentation (solo.hiero.org) which is always up to date with the latest Solo release.

Our generated documentation utilizes the Hugo toolset and customizable themes. Hugo is also used by the hiero.org website (see hiero-ledger/hiero-website) and countless other LF and CNCF projects. Gitbooks lacks the ability to separately version the docs at a sub-page or sub-site level. Additionally, Gitbooks is not very automation and generated documentation friendly.

Approach 2 & 3 feels very unfavorable and would require significant rework for the Solo committers and maintainers. Most likely these approaches would also remove our ability to provide our users with automatically generated and versioned documentation.

As a Solo maintainer, I am all for standardizing the theme, logo, colors, fonts, etc of our docs as closely as possible to match the requirements of branding/marketing kit, if one is provided. However, at this time (and to the best of my knowledge) no such specification or materials kit has been provided to the Hiero community.

[hendrikebbers]

Gitbooks lacks the ability to version the docs at a sub-page or sub-site level separately.

Agree and really dislike it

On the other hand having a full search and ai support like we have at docs.hedera.com are really usefull features. With that I like the "choose between docs.hedera.com or do your own and only be referenced / linked at docs.hedera.com". At the end I would like to have an open and freee (no cost) solution that contains all benefits

[olsentorfinn]

I think the idea of setting some standards surrounding language and visual style guides are a great idea.

However, I think attempting to force all projects to leverage a single centralized source of documentation is unrealistic , counter to established practices even stifling creativity and meritable ideas from arising in community driven development.

If Option 2 depends on enforcing some kind of centralized single source documentation I think I have to weigh in on Option 1.

I'd like to revisit the concept of Option 2 if it was less limiting to contributors.

[jeromy-cannon]

As a maintainer of the hiero-ledger/solo project, I see Approach 1 as superior in the long term as it allows innovation and provides an opening for better solutions in the long term. Every technology is developed for a specific set of use cases, no technology is the best solution for all use cases.

I've seen too many times in my career where a specific technology was enforced as 'the' technology to use, and the price tag to abandon a decision that was no longer advantageous became too expensive to consider.

I do think it would be advisable to give projects guidelines in regards to which technology to use for their docs, so that they can either follow an existing pattern that best fits their project, or deviate from the standard understanding that while deviating from the standard might be more difficult, it also might be less work in the long run given their particular use case.

[hendrikebbers]

I totally agree. My wish would be to allow every project to use docs.hiero.org (just edit/add markdown and do not take care of hosting/framework/...). But that is not a must. In general a project can use whatever makes sense for the project but we can provide a "best practice" solution that already has the Hiero style and so on

[hendrikebbers]

solo doc is based on https://www.docsy.dev

[rbarker-dev]

Is this solo action? Or solo itself?

[nathanklick]

Solo (eg: solo.hiero.org)

[may-hashpack]

Per the discussion in the TSC Meeting, @jwagantall has let us know that LF has a recommendation for documentation using MkDocs: https://lf-decentralized-trust.github.io/governance/guidelines/project-best-practices.html#documentation

It isn't an enforced standard, just a recommendation, noting it here for future reference.

[Reccetech]

Hi All.

Thanks to everyone's comments and feedback. Per the TSC meeting today we have consensus around Option 1 in that individual projects can build out docs as they see fit. It was recommended that the Hiero Docs Community Group put together a Style guide to try and have consistency between Hiero docs.
I have taken a first pass at that Hiero Docs Style Guide attached which is based on the look and feel of the current docs.hiero.org website.

In terms of next steps I would propose:

1. The Hiero Docs Community Group reviews and approves a final Hiero Docs Style Guide
2. We publish that Hiero Docs Style Guide on docs.hiero.org as a reference for all Hiero projects building out their docs.
   Hiero Docs Style Guide (1).pdf

Comments and feedback welcomed.

[nathanklick]

It would also be great if the branding kit included a simple HTML/CSS template.

[Reccetech]

@nathanklick
Hiero logos are available in different formats here: https://www.lfdecentralizedtrust.org/logos-guidelines
To this I agree we need to add the Hiero logo for dark mode, and Hiero favicon icons. Anything else? @jwagantall
The guidelines call for the use of Sans-serif font which is widely supported in tooling including Hugo. As we are asking for a basic font and nothing exotic I am not sure we need to supply it.
In terms of desired look and feel - I am suggesting docs.hiero.org should be the reference.

Hope this helps.

Best Regards,
Keith

[rbarker-dev]

I agree with what Nathan is asking for. We should have a documentation-brand-kit repo or some such that contains examples, guidelines, etc.

[Reccetech]

Can you provide an example of this "brand-kit" from another project to give me an idea what you are looking for? I have seen many brand-kits when it comes to logos or trademark usage - but never websites. Again we do have an entire website "docs.hiero.org" which I am saying can be used as the template for examples, guidelines etc.
I would also say that AI has made a lot of this much easier. Please find attached a Hugo theme I quickly created using docs.hiero.org as a template. This is not production ready - but just an example of what AI can pump out pretty quickly.
hiero-docs-theme-complete-v1.1.0.zip

[rbarker-dev]

From CNCF > https://www.cncf.io/brand-guidelines/#downloads-and-fun-stuff
From LF > https://www.linuxfoundation.org/brand-guidelines
From Red Hat > https://www.redhat.com/en/about/brand/standards

[jwagantall]

@Reccetech , I brought up this conversation internally to my team. We can certainly leverage the help of the LFDT marketing team to help us putting together a kit like the one @rbarker-dev mentioned with logos, presentations templates, document templates and anything else we need. I need your help defining this request and adding an itemized list of what things we want included in this kit (depending on what the project is gonna need the most). I suggest that this lives in the docs repo since this will be the main documentation landing spot that contains references to other projects docs links. IMO, just to make is easier to manage and to locate.

Do we need to appoint a marketing representative to review content and blog posts, and support content promotion throughout the course of the project? If this is the case, then my team recommends that we designate (or hire) a maintainer responsible for this whom we can put in touch with the LFDT marketing team initially to speed up their bring up process and will be responsible for the mentioned tasks.

[Reccetech]

@jwagantall So in the context of a docs website we can look to docs.hedera.com or docs.hiero.org as a reference. In both cases we see the primary branding usage is a logo in the top left corner. So usually logo guidelines will dictate items like the need to not distort the logo, correct color contrast, and any whitespace requirements. Most of this seems to be already covered here. I think much of this is coming up in context to the Solo docs site so perhaps @olsentorfinn can call out any other items that might be needed.

On the topic of having a marketing representative review content like Hiero blog posts and support content promotion for Hiero community projects (i.e. the Python SDK). I'd like to tie in reps from the Hashgraph marketing team to get their input. @DevinHashgraph @ed-marquez
Thanks!