Documentation and Wiki

Hey all! In the interest of easing new people to the project, especially as it grows more complicated, we have a need to document how to open it, how to launch the game, and how to use the various systems that you (and we) are writing.

Our current thinking is to use the Github Wiki to host this documentation. I have already put a few pages up, including some great docs written by @davejrodriguez for his pooling system. You can see from the sidebar what's the rough plan for the structure.

And don't worry: we will also add something within the project, both to link the repo, the wiki, and anything useful to get started with it. Probably implement a couple of in-editor tutorials too.

Now the question is: how do we create a workflow for this? Unfortunately it's not possible to open PRs against the wiki. It's not a branch, it's a different repo!

My current thinking is: you can host the .md files on your repos (wherever you want), and then you open an Issue when you want to "push" them to the wiki. Inside the issue you provide a link to the .md file. After that, for us it's just a couple of clicks if the file is properly formatted.

Comments and ideas are welcome

 

I like the proposed structure of the wiki. Looking forward to seeing more systems filled out!

My initial reaction to this is it sounds like a misuse of Issues. Why not have a top-level "docs" or "Documentation" folder in the repo? Collaborators would be able to submit proper PRs to it (enforcing GitHub markdown format and a sensible docs folder structure via Conventions). Then maintainers can pull information from this folder to construct the wiki.

 

But how do we pull it? We wouldn't accept the PRs, since the .md files would have to be in the wiki repo, not in the folder they are submitted to... also, what do we do, do we keep an empty folder at the root just to act as a target for the PRs?
... hmmm...

 

No, no empty folder. I mean actually have a "copy" (really an "original") of the documentation on the main repo. You would accept and really merge valid changes to the documentation on the main repo and just copy/adapt the markdown files to the wiki. You'd already be doing the last part with the Issues method if I'm understanding correctly. But this way, we'd be using the features correctly, be able to easily tell who changed what and when.

Main Repo
.github
UOP1_Project
Documentation

• images
  • StateMachineDiagram.png
  • PoolDiagram.png
  • FactoryDiagram.png
• StateMachine.md
• Pool.md
• Factory.md
• etc.

And it doesn't have to be the above folder structure. Just trying to give a general idea.

 

Uhm, yeah, sounds good on paper, but then we lose the ability to make quick edits to the Wiki. We would have to make edits in the repo first, and copy/paste them manually in the Wiki every time. Otherwise if we don't do that, next time we copy-paste from repo to Wiki, we would overwrite these quick edits.

Right now it's really good to be able to just do quick edits as soon as I spot a mistake. By having things in the repo as the "original", this process would become much longer and wouldn't scale as the game (and the Docs) grow.

 

What happens if you make a quick edit on a file that someone has cloned and they make an issue with their version of the file without your changes?

 

In any case, I think the workflow question should probably be left to the maintainers. You all will be the ones most affected by this decision. If submitting wiki changes via Issues is easiest for you, then I'm fine with it.

 

I think it would be a good idea to link the Code Conventions by @davejrodriguez from the Contribution Guidelines. I honestly didn't know the Code Convention document existed as I didn't immediately explore the GitHub Wiki. The Contribution Guidelines document is very high profile and was the main document I used to get started.

 

Good suggestion, I linked it on the main Readme (and it's in the Wiki's home too).

 

@jandd661 Just to clarify, I did not write that document That document was crafted by the maintainers of the project with some input from the community early on.

 

@cirocontinisio @Sarai I would like to document the dialogue manager

 

It is Demanded to create the some realize notes to every system, which will fixed the major changes in them (new features or changing features).
By example, the Loading system (at state "The Journey: Ep. 2 | Open Projects") didn't have the EditorInitializer prefab, but in the realize "The Journey: Ep. 3 | Open Projects" it exist. If you try to find - when it was changed and why, it will not simple - you can search the thread Scene Loading and find some not specific marked post @Amel-Unity.
Will be more conform, especially for new participant to look to some, by example, the "Scene Loading Notes":
v.1.0: Initial realize
....
v.1.1: Added the the Prefab "EditorInitializer" (post)
or
the "Working dialogue and cutscene systems Notes":
v.1.0: Initial realize
....
v.1.1: improvement Cutscene/Dialogue System (PR)

Short note & link to PR or to the post in forum thread which described changes more detail.
In other case demanding to make search by all posts in thread (some of them is very big) or update "Documentation and Wiki" regular.
Based on it notes the "tech writer" can update and write Wiki (notes write that who make changes).
Notes files can store in separate files (on google doc? question with managing write access)
or
It can be special marked post in corresponding threads (Who made the changes, It takes the prev post, add new own part and make new post)
As other variant to do the post corresponding to change code more structured (some rules), At now it losting in threads.
P.S> Wiki Is Great!!!

 

@cirocontinisio @Amel-Unity I will try make the document for the Event system & Scene Loading

 

@cirocontinisio @Amel-Unity
Why you (??? may be not you) hide You lost link in Sidebar To description for Event system - "Event-system.md"
if put to "_Sidebar.md" the correct row
"* [Event system](https://github.com/UnityTechnologies/open-project-1/wiki/Event-system)"
vs "* Event system"
It show wiki page for Event system
I didn't find the information that that wike part was taken in work
I Understood - you think you did it, but because of lost link your work doesn't show in Sidebar

@cirocontinisio
I found in wiki that for link on pictures (schemes etc.) using some file sharing services like imgur.com (e.g. https://i.imgur.com/uqZy52F.png for Object Pooling). This is not good, because it will not be stored for a long time.

I recommend (I check it work for my own repo) to create additional folder "WikiPictures" in root of github project (on one level with .github and UOP1_Project folders) and put here all pictures for wiki page.
In this case all link to pictures will be in style like "https://github.com/UnityTechnologies/open-project-1/blob/master/WikiPictures/SK944jh.png)" and will store as long as exist repository.
To avoidance of ambiguity - pictures name must contain the name of wiki page (e.g. Event-systemDiagram.png)

 

Yes, you're right. It was a quick solution but we need to patch it.

Thanks @Emikey1, but it's a bit early, we're still under some decent work in progress! I'll poke you if we think it's in a state that can be documented. Alternatively you can write some high-level description? Did you watch the livestream where we describe it?

 

@cirocontinisio @Amel-Unity Will you correct the "_Sidebar.md" self or Will be more correct to make corresponding PR for Wiki?

 

Fixed everything