Propose HIPE: Indy Docs Repo

[mjmckean]

indy-docs-repo HIPE

Signed-off-by: Michael Joseph McKean mjmckean11@gmail.com

[nage]

This HIPE doesn't talk about where each doc lives. We would rather not centralize this content into one github repo. Please explain how the content is pulled into the github.io page.

[dhh1128]

I would like this HIPE to talk a bit about release formalities: how do docs get updated in conjunction with a formal release of a particular repo? How are they labeled? How is the version of the docs discovered and matched to the version of the code? Etc?

[mjmckean]

Thank you for the feedback!

@nage after some discussion, we revised the HIPE to focus on a Read The Docs hosting. The process of pulling the content is now described more clearly in the tutorial.

A good topic for discussion is whether or not to have this content centralized in one repo. We did briefly elaborate on some drawbacks for both situations; however, this topic may still have much to be discussed.

@dhh1128 we added a versioning section to address your questions. Open to any and all discussion.

[TechWritingWhiz]

I think moving to the Read the Docs is a great solution. Hyperledger Fabric does it as mentioned. There are drawbacks. However, the logic seems binary. If Hyperledger Indy wants to have the reputation of easy onboarding, less confusion about the docs and known for having things up-to-date, then moving to Read the Docs will need to be done.

A previous solution proposed was to pull the "onboarding" type documentation into Read the Docs and to then leave the "grittier" developer docs within the doc folder of each repo it pertains to.

Regardless of which solution is chosen, it seems that Read the Docs is the best solution to move forward with and efforts should be made toward that end. It may cause pain initially, but once it's done, it's done, outside of maintenance of course.

If the end goal is to reach a place where Indy documentation is as consistent as for example, Fabric's (and in keeping in continuance with the Hyperledger brand), then moving to Read the Docs must be done.

Recommendations for scaling the work:

• 1 maintainer = moving "onboarding" docs to Read the Docs first
• 2 maintainers = moving Release Notes along with "onboarding" docs
• 3 maintainers = the above + cleaning up the docs folder in each repo along with adding a reference link to the new Read the Docs location at each README in all the repos.
• 4 maintainers = all of the above plus coordinating the move of each repo specific doc folder to Read the Docs if that is what is decided to do.

[burdettadam]

status update: mjmckean and I are addressing concerns from the community and working on a demonstration for this hipe.

[michaeldboyd]

This PR can be closed in favor of #63

[TelegramSam]

Closed in favor of already merged #63