Documentation

[techtolentino]

Question 🧐

Should we have a dedicated repo for team/project-related documentation?

Why

As a team, we manage and operate on multiple projects, each with their own respective repositories. For documentation, some repos have more supporting docs than others.

Current, existing examples:

• qiskit.org https://github.com/Qiskit/qiskit.org/wiki
• platypus https://github.com/qiskit-community/platypus/tree/main/docs

Things to consider

• some of us are aware of certain protocols/practices that others might find useful
• some information is internal to the company, some can be public
• some of our team practices are captured in the qiskit org wiki, but they apply to other projects as well
• as the team grows / changes, or as we partner with other Qiskit themes, a dedicated repo could be helpful

We'd love to hear your thoughts on this.

Thanks

[vabarbosa]

i am all for this! having a central repository where we can document our processes, practices, etc. (that are either internal or applies across multiple projects) is greatly needed. at the moment we have docs across multiple repos, wikis, box notes, etc. it would be great to consolidate these into a single location available to the entire team.

with that being said, some information should reside within the appropriate repo, but that decision be made on a per repo/content basis.

[eddybrando]

I see the points you make @techtolentino, and I like the idea.

I think we can break this down in two important goals:

1. Centralise documentation relevant to all projects.
2. Protect internal documentation.

Centralise documentation relevant to all projects

I believe we should in fact have a central place were globally relevant documentation as well as best practices for our work can be found.

This might live in this central repository (Qiskit/qiskit.org), but the location could be misleading and hard to find for new contributors.

As for using the "Wiki" section of the repository, I'm personally not a big fan. In my opinion, lacking a history archive and information about updates is a major disadvantage when comparing it to storing the documentation in Git.

The only concern I have with creating a new repo for this, is the fact that we would now have an additional project to maintain. But given that it cannot fit into solely one other project, it makes sense.

Protect internal documentation

There aren't many discussion that require storing internal documentation, but when we do, we could in fact use a more structured and centralised way of storing this new information.

The first thing that came to mind was using some other regular cloud storage system (like Box), since internal documentation might be mostly well represented in written form and using images. This might be easier to maintain in a regular document-like format instead of, for instance, markdown code.

If we choose to go for storing it in GitHub as well, I'd also propose to create a private documentation project for sensible data.

The same concern about adding an additional project to maintain applies here. But it is true that we should choose a way to structure this, given that our projects are growing in complexity.

Proposals

1. Create two repositories

One public for global documentation (team practices, code guidelines, architecture, overview of projects, ...) and one private for internal and sensible documentation (deployment information, team onboarding, internal processes, ...).

2. Create one repository and one box folder

One public repository for the global documentation and one box folder to store the internal and sensible documentation.

---

Team, what do you think? Do you agree with one of this proposals? Do you have a different one?

[techtolentino]

@eddybrando - thank you for elaborating your thoughts here.

As for using the "Wiki" section of the repository, I'm personally not a big fan. In my opinion, lacking a history archive and information about updates is a major disadvantage when comparing it to storing the documentation in Git.

I agree with this. Although in the past I've suggested and even contributed to wiki docs, there's just something about it that's lacking. I've also seen cases where a lot of effort is spent building out the wiki, only for it to be underused and sometimes, flat-out ignored.

I lean towards Option 2...