It came up recently that the lack of documentation for the Lua Scenario Template (LST) is making it more difficult to use Lua Events and to get help once someone has started. Since documenting the LST is a priority now, I figure we should discuss how to get it done. I won't be in a position to do much of it myself for at least the next few months.
I think there are three aspects to documenting the LST:
1. The "Learn the Basics" Tutorial.
I think this is the most important part, though it is also the most difficult. This is the introduction to programming as well as the introduction to using the LST. Writing this sort of guide is fairly time consuming, since you have to think of what to explain, and how to explain it. You also have to write examples, make sure they work, and explain why they work. Furthermore, you'll have to keep various stages of an example scenario.
On the plus side, a lot of this work has already been done in my Get Started With Lua Events guide. If the same Classic Rome scenario is used, many of the examples can be reused with almost no modification. However, some significant modifications would still be needed. For example, I left using the state table until the last lesson, I think because I wanted to show how to make flag and counter modules first. With the template, using flags and counters should be a fairly early topic, even if making more direct access to the state table is left for later.
With this sort of intro to Lua programming with Civ II, it would give a place for people to start learning, as well as a 'reference book' of sorts to link to.
So that we can incorporate work that has already been done, I would find it very helpful if people could post links to good question and answer exchanges.
2. The "What's Available" Documentation.
I've written a lot of code for the LST. I did write comments for much of it, however it is generally in the "LuaCore" files, for which my general advice is "don't touch unless you know what you're doing". This is a bit of a contradiction. This information needs to be taken out of the .lua files. In principle, this shouldn't be too difficult, since it is basically taking the comments already in the code and formatting them. However, examples would probably help, and I may need to provide extra insight from time to time.
Although this should be an easier job, it is also much easier to offer help for. "How do I do this" can be easily answered by cutting and pasting the function description from the appropriate module.
3. The "How Does the LST Work" documentation.
While this should be done eventually, I'm thinking that at the moment it makes more sense to explain the nuts and bolts on a case by case basis, since we only have a couple people around that are at the skill level to need this info at the moment. This is also something that I'll have to do myself, since I'd have to explain the information to someone else anyway in order to delegate.
I think this is what has to be done, though feel free to tell me if you think something was left out.
Now there is the question of how to do this. If someone wants to volunteer to be the "writer" for the entire project, then, obviously, they can do it how they like. This is more feasible for the "What's Available" documentation, where someone can decide to take responsibility for one module at a time.
Assuming that no one wants to be the one person to put together the entire "Learn the Basics" Tutorial, we need to decide how to coordinate. The Scenario League Wiki is the obvious choice, but it has a couple drawbacks.
First, is that there is no syntax highlighting, so we have to paste in pictures of the code, as well as copying in the code as text. (I also seem to remember having to do something weird so the code blocks would have proper indentation.) Second, is that there isn't a way to hide some text, if you want to have 'exercises'. I suppose we could have separate pages for the answers.
These aren't deal breakers by any means, but I'm open to other suggestions.
Are there any comments or concerns, or other documentation issues that should be addressed?
I think there are three aspects to documenting the LST:
1. The "Learn the Basics" Tutorial.
I think this is the most important part, though it is also the most difficult. This is the introduction to programming as well as the introduction to using the LST. Writing this sort of guide is fairly time consuming, since you have to think of what to explain, and how to explain it. You also have to write examples, make sure they work, and explain why they work. Furthermore, you'll have to keep various stages of an example scenario.
On the plus side, a lot of this work has already been done in my Get Started With Lua Events guide. If the same Classic Rome scenario is used, many of the examples can be reused with almost no modification. However, some significant modifications would still be needed. For example, I left using the state table until the last lesson, I think because I wanted to show how to make flag and counter modules first. With the template, using flags and counters should be a fairly early topic, even if making more direct access to the state table is left for later.
With this sort of intro to Lua programming with Civ II, it would give a place for people to start learning, as well as a 'reference book' of sorts to link to.
So that we can incorporate work that has already been done, I would find it very helpful if people could post links to good question and answer exchanges.
2. The "What's Available" Documentation.
I've written a lot of code for the LST. I did write comments for much of it, however it is generally in the "LuaCore" files, for which my general advice is "don't touch unless you know what you're doing". This is a bit of a contradiction. This information needs to be taken out of the .lua files. In principle, this shouldn't be too difficult, since it is basically taking the comments already in the code and formatting them. However, examples would probably help, and I may need to provide extra insight from time to time.
Although this should be an easier job, it is also much easier to offer help for. "How do I do this" can be easily answered by cutting and pasting the function description from the appropriate module.
3. The "How Does the LST Work" documentation.
While this should be done eventually, I'm thinking that at the moment it makes more sense to explain the nuts and bolts on a case by case basis, since we only have a couple people around that are at the skill level to need this info at the moment. This is also something that I'll have to do myself, since I'd have to explain the information to someone else anyway in order to delegate.
I think this is what has to be done, though feel free to tell me if you think something was left out.
Now there is the question of how to do this. If someone wants to volunteer to be the "writer" for the entire project, then, obviously, they can do it how they like. This is more feasible for the "What's Available" documentation, where someone can decide to take responsibility for one module at a time.
Assuming that no one wants to be the one person to put together the entire "Learn the Basics" Tutorial, we need to decide how to coordinate. The Scenario League Wiki is the obvious choice, but it has a couple drawbacks.
First, is that there is no syntax highlighting, so we have to paste in pictures of the code, as well as copying in the code as text. (I also seem to remember having to do something weird so the code blocks would have proper indentation.) Second, is that there isn't a way to hide some text, if you want to have 'exercises'. I suppose we could have separate pages for the answers.
These aren't deal breakers by any means, but I'm open to other suggestions.
Are there any comments or concerns, or other documentation issues that should be addressed?
