[Discussion] Project documentation system

[mikejbrown]

(Related issue: #214 ) I understand the core game is very much in flux right now and probably will be for a while, but going forward it would be good to have a standardized way to document the project. There are at least three categories of things I can think of that need (or ideally would have) up to date documentation:

• User level (i.e. installation, gameplay etc)
• Developer documentation (internal C# APIs for all classes, style guides etc)
• Modder documentation (LUA facing APIs, file organization & mod packaging guide etc)

You can probably think of other things.

At the moment this need is being filled as best as possible right now by code comments, the issue tracker and the project wiki. However, it would be great to have a centralized documentation source. To ease maintenance as much of the documentation build process should be as automated as possible. For example, something like Read the Docs is able to integrate with Github post-commit hooks, so that when a commit is made to master (say), the documentation is automatically rebuilt based on the updated project files and hosted on their server. Unfortunately ReadTheDocs uses the Sphinx documentation engine which is strongly geared to Python projects. Theoretically it works with C/C++ but I don't know about C# support. There is an offline C# tool Sandcastle Help File Builder (which I've never worked with), but it does not appear to be integrated with Github or a hosting service AFAIK. (BTW, I'm all for hosting on the wiki or on a Github pages page if most of the regular updating jobs can be automated.)

Basically I'm opening this issue to start a discussion about the best way to handle the documentation task down the track when the APIs are a little more settled. Hopefully we can get some people who are experienced with documenting large open source C# projects... because I'm definitely not!

[alexanderfast]

Both user and modder documentation is great to keep in the wiki, since they can both add to it. Until the game grows in complexity so much that it warrants setting up a dedicated wiki with with more features. But I dont see that happen in the foreseeable future.

As for the code/api documentation. I think that is irrelevant for open source project. You can look at the code and see what done. I take it to the extreme, if you look at the code and still dont understand whats going on and need documentation as well, then the code is wrong. Not to mention that code comments are sooo often forgotten to be updated when the code changes. They confuse more than the explain.

But, hey, each to their own, I dont have to use it.

If we want to go down that route there are StyleCop rules (currently disabled) that enforces that everything is documented.

[mikejbrown]

@Mizipzor I see your point that the wiki is probably fine for now. The only thing I worry about is keeping it up to date & consistent.

As to your second point: I must respectfully disagree that API documentation is irrelevant to an open source project. Python is an open source project and I have not once had to read internal python source to figure out how some language feature or library function needs to be used. Obviously that is an extreme example and ProjectPorcupine will never come anywhere near python in terms of number of people relying on the API... but there are plenty of other examples to go on as well.

Implementation is less important to document than API, unless an especially tricky algorithm has to be used, so detailed notes on how the current code works are probably as pointless as they would be hard to maintain. But I think documenting API is critical. Of course you are right that the problem is keeping the docs up to date as the code base evolves, but that is where an automated system can help enormously.

[alexanderfast]

For something like Python such documentation makes sense. Its code is used by many people and (big parts of) it doesnt change. I consider this project to small and to rapidly changing to warrant the effort of keeping documentation up to date.

But we can both have our way, right? If you want documentation, make it happen.

[bjubes]

No we need documentation. How do I add a feature so that it can be localized? I don't know, so I add one that is totally incompatable and leave a nightmare for someone else to totally reimplement my system, which I didn't document so they give up after an hour. And thus the game is fragmented and broken with no one with enough knowledge to fix the problem easily

[bjubes]

Also this is a non discussion, documenting changes is in the contributing file under best practices section

[mikejbrown]

@bjubes CONTRIBUTING.md says "Document your changes in your PR. If you add a feature that you expect others to use, explain exactly how future code should interact with your additions." which is great for features under active development but is not an ultimate documentation solution, e.g. we shouldn't expect a modder to search through year old closed PRs to find out the API they need to code to. They should just be able to go to the docs site and instantly have all the info they need nicely organized and up to date.

... of course I'm an idealist ...

[alexanderfast]

@bjubes I was talking specifically of the comments above a method or field, which is very different from the high level concept of, say, adding a feature. High level documentation is better.

[bjubes]

Agree, we need high level docs for large changes so devs don't get lost when large PRs are merged in overnight.

[FilippoLeon]

I'm starting a wiki page, where we can put a brief description of some core subsystem and briefly document how it works. (By core subsytem I mean Furniture, PowerSystem, Trading, Temperature, Oxygen, etc.). I, for instance, have completely no clue how the new power system works.

I propose the following temporary solution:

E.g. for my overlay system: document how to add new overlay trough xml + lua. Briefly describe how it works and what can be done next and who is working on what.

In fact, I think looking trough the Issues/PR will become increasing difficult. However, keeping a well documented code and PR is still very important.

There shoul also be a couple of "reference people" mentioned in the wiki, who woked/are working on the stuff.

Will be here: https://github.com/TeamPorcupine/ProjectPorcupine/wiki/How-does-it-work%3F

[crafty-geek]

bump As someone who just recently delved into the code with intent to modify a complex system (fixing the whole preferring-empty-stockpiles hauling behavior), it is WAY past time for a mass-commenting frenzy. Does StyleCop perhaps have a " public methods must be documented" rule that could be enabled? Or a "methods over L lines long must be documented" rule?

@FilippoLeon's "How does it work" page is good for getting ones toes wet, but a) it's woefully sparse, and b) there needs to be some standard so that one could get at minimum a cursory explanation of a method from within the code, rather than having to open another window. Ostensibly-descriptive method names have an annoying habit of failing to be descriptive enough, especially for newbies.

As a Visual Studio / IntelliSense user, I'm partial to just typing /// above whatever new methods/fields/etc I add and filling out that overview/params/return value template (as it integrates quite seamlessly with IntelliSense - you can literally see the function's documentation as you're writing a call to it, so you can figure out what goes where and differentiate between different parameter sets for the same function name); however, if there's a more popular IDE among devs on this project, I'd yield to whatever is the most automated/smooth way of getting similar integration with its systems. (Is there a way to do a poll on Githug to see what IDEs are most popular? Or maybe someone with more dev experience than I can whip up a strawpoll with the common IDEs listed? Off the top of my head, I know a slew of Java-specific IDEs, Monodevelop, and Visual Studio)

Can we schedule a Documentation Day/Docs Weekend in the near future? Perhaps working around @quill18's schedule so that a) code that he wrote can be definitively documented by the original dev, and b) it can be "sanctioned" to the point that it's worthy of an announcement on quill18creates (to perhaps rekindle interest for people who took one look at the lack of docs and bolted from development)

If there's been further organization/movement on documentation in other issues, apologies for resurrecting an old issue.

[bjubes]

I don't comments because something is long, but other than that I agree with @crafty-geek, we need some major documentation beyond what is listed currently on the wiki