How to structure documentation?

[andreaadao]

Hey there!

I took the task of proposing a structure for documentation, and I'm opening this discussion with a couple of questions for us to keep in mind while making proposals.

1. What is this documentation for now, in this phase of the project?
   Manage content (writing, editing, sharing for feedback)?
   Creating documentation for Colab?
   Or both?

2. Where is the best place to keep it accessible to both readers and contributors, while keeping track of changes and versions' history?
   GitBook?
   Are GitHub's wikis enough?
   Or should we keep using Google Drive and Docs for now?

This thread is for proposals and sharing updates of the tests made.
You're welcome to join the discussion and invited to participate and contribute!

PS: Wasn't able to connect this discussion to the task already created. It seems to only let me create one from the discussion. Is there any other way?

[andreaadao]

For me, the most important in this phase is to for us to have a space to manage content together. Now, we'll be creating and developing a bunch of content to give a context to Colab, from explaining it, to building the framework, making the website, and sharing its proposals with the world; and as I see it, Colab's documentation will come afterwards or during this process, so I'm not so worried about whether the space we decide to use will already serve that purpose, or not.

So far, I've made a few tests on GitBook and here with GitHub Wikis and looked at what was being done here and there, and how people use it for different purposes (there's people blogging in these spaces!, managing teams, making websites of them 🤔).

First notes, impressions and findings:

• GitHub Wiki:
  • Is here in the same environment, no need to go/login anywhere else.
  • Is quite simple to use.
  • Doesn't let create folders, but each page can have sections (shown in the sidebar by default, which helps navigation).
  • Here are some examples of wikis: https://github.com/MyHoneyBadger/awesome-github-wiki.
• GitBook has a more intuitive and attractive interface.
  • For who's editing and reading.
  • Has collections, spaces, pages and subpages, which give us a few more options for organizing content.
• Both let us keep track of changes and changes requests, compare versions.
• Both can be connected to repositories.
  This makes it easier to understand the content in context. And, since we have here a way of bringing up discussions and making the needed connections and proposals between the different working environments, we won't loose anything anyway.
  • On GitHub Wikis that's how it works, can't do it otherwise.
  • On GitBook we can connect spaces to repositories (and specific branches as well) to GitHub — https://docs.gitbook.com/getting-started/git-sync/bi-directional-git-integration.
    "When you edit on GitBook, every change request merge will result in a commit to your selected GitHub branch. When you commit to GitHub, every commit will be synced to your GitBook space."
• Testing out any of them will for sure make us improve and share best practices in how we organize and structure content/documentation
  Since we're so used to Google Drive and Docs, this is an opportunity to challenge ourselves and find out other ways and tools of making things together.

Do you have any question to add to this discussion about these two options?
What else do you think we should be looking into?

[ayoreis]

You can kind of create folders in wikis with sidebars, the only problem is each time anyone adds a page the sidebar need to be manualy updated.

https://docs.github.com/en/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki

[andreaadao]

Cool!
I've only tested the sidebar's default version, you can check here:https://github.com/colab-at/colab/wiki/Welcome!-I'm-testing-the-wiki

In this case the folder aspect of the page is created by its own content, when adding headings to it.

[uxte]

I'm thinking of documentation as in a guide on how to use Colab. Like a playbook.
In this phase though the most important for me is how we discuss and keep track of changes in content that we are creating, descriptions, websites, etc.

For this I was thinking we could use text files in a repository. For example we could have a Repo for "website content" and in it text files per section and/or page.

For the documentation/playbook I'm willing to try Git's Wiki or GitBook but now that I saw the examples from @MyHoneyBadger I don't see enough reasons to use GitBook. I guess only trying the two.

[uxte]

One reason to start already a documentation repository is that some of the content is already part of documentation of What is Colab i.e. Principles. And we should have that development process "documented".

[andreaadao]

Agree with using the text files in repos for managing/creating content in general. I like the idea of having it developed in context, I think it's quite intuitive and makes it easier for anyone interested to find it.

For the documentation, it can even be a repo as well, in the same way we're proposing to do the website-content repo. And we can be organising the content in a wiki or a GitBook at the same time it gets refined, as preparing it to be presenteded in a different format also helps structuring it.

[uxte]

While @riikkaeveliina is with Write description for Colab's process we could use it as a way to experiment with real content. Maybe a text file first? Which repository?

[ayoreis]

I think in the colab repo since the description will be used for more than the website, else it could go in website-content.

[andreaadao]

I also think it should be on colab's repo, since it has to do with the project in general. We'll need to revisit it later for the website content, and that process can happen on its own repo (website-content).

[Kako29-03]

I agree it should go to the Colab repo. Since it will be used for more than one thing then it should be in the biggest of those things, in this case, between the Colab repo and the Website repo, i think it suits better the Colab repo.

[ayoreis]

I think wikis are best while we want to host the documentation here in GitHub, but if we only want to manage the content here and then display it in a website, markdown files in a repo work better. It is very easy to switch in the future so I think we should start with the wiki.

[Kako29-03]

After reading all of this and exploring a bit I feel that both will require the same amount of capacity to start and try out, so I think we should go for the simplest and easiest one to start with: the Wiki.
Since there are so many of us that are still not comfortable with GitHub and still learning a lot about it, staying here will make us get more used to using it and interacting with it.

For the future I think we should use GitBooks. For me it looks better, easier on the eyes and is more readable. Especially to those not used to GitHub. I feel it will be way more open and accessible using GitBooks.

[andreaadao]

Just to make sure, here your comment is related to creating documentation for Colab (playbook like, how to use Colab), right?

[Kako29-03]

Yes

[andreaadao]

#update #proposal

I think we have/know enough to start experimenting:

• We'll be using repository files to manage content, create, share, edit, and have that process documented.
• The file should be created in context, in the repository where the content is more useful.
  ie: If writing a description for the website's about section, the file to create and manage that content should be added to the website-content repo.
• In this first phase of creating content, we'll be using Colab repo for both managing content and creating Colab's documentation.
• We'll reorganize Colab repo and readjust its purpose for its next phase, as soon as:
  • we feel that this space is too limited for Colab's documentation,
  • or that we're all comfortable with testing another tool (such as git's Wiki, GitBook, or something else),
  • or that we have enough to start building the playbook.

I'm considering the Propose structure for the documentation task done, and breaking its next version in several more:

• Make How to: Organize content

  • Make How to: Organize a repository
  • Make How to: Manage files in repositories
  • Make How to: Create readme.md files

• Find the best place to store these How tos, to create the organization's toolbox for contributors.
  Any ideas @ayoreis ? Could it be on .github special repo ? Also thought of Colab (meta) board, but I think I would prefer to have it in a cleaner space. A wiki? :)
  This can be the start of Colab's own "Community health files".

Is anything else missing?