Update the manual
Opened this issue · 13 comments
The manual was written for Godot 2.1 in 2016, and since there has been changes to both Godot and Escoria since then, it's no longer completely accurate. In the spirit of FLOSS, it would be nice if the source was made available and open for contributions.
My proposition is that the original website is not changed, since it has value as a historical document, but that the project is converted to markdown and placed in a new repository on GitHub with interlinking between pages of the manual. That will lower the bar for contributions and make sure there always exists a high quality tutorial for Escoria.
EDIT: Things to update:
- Change references to .spx files to .vox
Hi @fleskesvor !
Yes I agree the documentation should be updated, but you can actually edit the manual directly on the flossmanual platform (on the link you provided), you just have to create an account, and it's open to contributions. It's not perfect but it allow to export to PDF and to prepare books for printing...
And yes we can also keep this version and create a 3.0 version ;)
Don't misunderstand me, I'm not against converting to markdown and create a Github repository for documentation on Github, but that's work... and no everyone is skilled with Git, so it's not so easy for contributors. Mostly I believe we can spend this time directly on improving the documentation on the existing platform ;)
@flossmanualsfr what do you think ?
I guess I'm partly to blame for bringing up documentation so I could maybe pitch in a bit ;)
The idea of a GitHub wiki was also suggested, and I think that might be a logical direction as well.
Work cannot be avoided, and preferably all the screenshots would need to be re-taken in Godot 3. Documentation, in general, lags behind because it's such a big job to keep up to date.
I am not sure there's any value in retaining a 2.1 version of the manual, because afaict the 2.1 branch
in Escoria is unmaintained.
I did create an account on flossmanuals and it seems like a fairly typical wysiwyg editor. I tend to prefer ReStructured Text, or Markdown, over html, but if everyone else prefers the current system, I suppose it's fine.
Avez-vous des menus en anglais? L'icon avec le livre dire "FR" et n'est pas clickable. Il fait mal au mon tête en francais des menus liser car je ne actuellement parle francais, desolé :( Mais j'ai etudié un peu en l'êcole!
Hmm, I think it's up to @flossmanualsfr (and @cedricgemy) to answer here, for me if you want to spend time converting to another platform/format it's ok as long as it is FLOSS, but the French Flossmanuals association did spend time and resources on this book, so IMHO they have rights to "keep" it on their platform as a proof of their work.
Any way, it's open source, you are free to do it by the licence ;)
I also agree that's really an issue and it's bad if you can't use the interface in english...
Another solution may be to move the 3.0 book to the english flossmanuals association website : http://en.flossmanuals.net/ and keep the 2.1 on the french one.
But let's see what @flossmanualsfr think of this before moving please !
Yes I agree the documentation should be updated, but you can actually edit the manual directly on the flossmanual platform (on the link you provided), you just have to create an account, and it's open to contributions. It's not perfect but it allow to export to PDF and to prepare books for printing...
I didn't realize this was possible. I hunted around for an option to register an account on the English version of the site, without luck, until I finally stumbled over it, hidden behind some French I didn't understand. If the relevant texts could be displayed in both French and English, this doesn't seem like a bad option for keeping the tutorial up to date.
And yes we can also keep this version and create a 3.0 version ;)
Since you can export to PDF, I think it would be good enough to just offer a link to a PDF version of the 2.1 tutorial and update the current one, but that's up to you.
Maybe we should make a list of texts and images to update and any new and/or undocumented features and just go from there.
doing a list of updates would be a first step, and will certainly be necessary. I would say the sooner the better, having up2date docs is more helpful.
For collaboration annotations, we usually create a chapter in the book and drag it at the bottom (left chapters) to make it unavailable to reader.
I’m not aware on how to make a book available for download in the "read" section of the website. I’m waiting for yemanjalisa’s advice for it.
i created : "to be updated for v3" chapter
@cedricgemy https://github.com/godotengine/escoria/issues/45 is an unordered, unorganized dump of my findings.
There are also things that would make the code more readable, like I just mentioned on IRC/#escoria that use_action_menu for objects would be better called is_interactive and the documentation updated to reflect that this is relevant only when hud.tscn is configured for the action menu. This because the object really doesn't determine which menu style is used.
Of course the documentation could also be updated to say that both verb and action menus can be used together, if they can be, as I think they can be, although the game might feel a bit weird in that case.
@cedricgemy Where did you create that chapter? I can't find it.
Would it be fastest for someone to pull a 2.1 backup of the current book and host it, so the contents can be directly updated?
This is a bit confusing with different people holding ownership of the documentation from the people who are collaborators or contributors to the project :(
i created : "to be updated for v3" chapter
I didn't find it yet either, but is that a workspace for copying whole pages of the current tutorial and rewriting them for Godot 3.0? For the list of things to update, I think a task list on GitHub would be easiest. I can start adding one to the first post of this issue, which you will also be able to edit, since you are collaborators.
This is a bit confusing with different people holding ownership of the documentation from the people who are collaborators or contributors to the project :(
This is actually more of a tutorial though, and while it's not directly related to Escoria, it does sort of compensate for the lack of proper documentation, while also giving good instructions on actual implementation. I think it actually might be a good idea if Escoria also expanded on the currently bare-bones documentation to provide more in-depth information about functionality that might not be a good fit for a tutorial. The two would complement eachother nicely, I think.
I just did a full proofreading, added missing sections (in particular in the first-game part) and clarified some others.
The book is open for anyone to edit AFAICS (I just created an account there and edited it straight away).
I believe the book (and all the screenshots) can be upgraded to v3 in a second step when Escoria3 is stable. Right before that we'll need @flossmanualsfr to freeze a version of the book for reference.
I would like to contribute into upgrading Dazia 2 to Dazia 3
Hey, did #19 fix this issue, or are the docs in this repo still out of date?