Improve WALA documentation and web site

[msridhar]

The WALA documentation has several problems:

• There is no clear guide for getting started with WALA using artifacts from Maven Central (i.e., without building from source code). For the most part, building from source should only be needed when you are hacking on WALA itself.
• While there are a lot of good documentation pages, there is no good top-level guide indicating how to get to those pages and in what order they should be read.
• Much of the documentation lives on MediaWiki in Sourceforge, which is outdated and needs to be retired.

I think we can make some moderate improvements to the situation with some re-organization that shouldn't require an enormous amount of work. We can aim to consolidate all resources on GitHub and have https://wala.sourceforge.net simply be a forwarding pointer.

I'm creating this issue as an umbrella for this work. If others have thoughts on how we can improve documentation and onboarding, we can discuss here.

/cc @liblit @juliandolby

[QRXqrx]

I'm glad to hear this news. As a noob in program analysis, it's really difficult to get start with WALA. Some of my school mates are using WALA, too, and all of us are using the release version on maven center. So I think it's may be a good idea to reorganise the document according to this PPT: PLDI_WALA_Tutorial.pdf. You can enlarge this PPT by adding introductions of new features. Teaching users how to use WALA to build easy examples themselves by creating some simple scenaries and give out corresponding codes maybe also useful :-)

[aliahsan07]

one big issue is the docs and even the main repo readme doesn't have any description on how to get started with WALA or how to run WALA on a sample program. It feels like it has a higher learning curve than other tools.

[msridhar]

I am first working on getting rid of the MediaWiki installation on Sourceforge and migrating all extant docs to GitHub. The content of the main page of the wiki will go into README.md; WIP here. The remaining (relevant) wiki pages will be moved to the GitHub wiki if they haven't been already.

I believe that https://wala.sourceforge.net should remain the WALA home page. That is how WALA has been cited for years and I don't want to have people start citing some other web page at this point. So I plan to replace the Sourceforge wiki with a simple static page, whose content mostly mirrors the README.md here.

Once this migration is complete I will work on some documentation re-organization, culling of out-of-date instructions, and some simpler examples. Feedback on this plan is welcome @liblit @juliandolby

[Leo0426]

Hello sir, I am new here. And i am currently learning WALA. For me, i have four key point in my road-map. I recommend to write in the documentation for understand WALA more. - First, i think i must know some basic knowledge of WALA dependence, such as i should know the relationship between WALA and Principles of Compilation, the relationship between WALA and static-code analysis, etc. It's great for new to understand WALA.
- Second, i've chosen to download the code and run the test case, but the new version code doesn't have a correct document. For e.g, the wiki said when run WALA we should copy 'dat/wala.perperties.sample' to 'dat/wala.perperties', but i cann't find 'dat' folder. In the end, i find 'wala.perperties.sample' file is in the resources folder, and also should convert to wala.perperties in resource folder, then my WALA project run correctly. So I think the wiki doc should update by WALA's version. - Third, I know WALA has a lot of useful test, this very kind for me. I run the program, debug the program, and then try to know the entity meaning in WALA.The tutorial.pdf offer detail technical support, it can be write to wiki. - Finally, I can try to use WALA to do something for my own application. If possible, we can introduce some application scenarios in wiki.

I don’t know if my road-map is right or not, because I’m still learning. I am also doing the resources integration and translation of WALA, my project is : 'https://github.com/Leo0426/WALA-improve', I will be keep improving and updating it. If there is a problem with my road-map, please let me know. Thank you very much. I hope I can have opportunity to join the project in the future. I will feel very honored.

[msridhar]

@Leo0426 I am very sorry for my super slow response here. I agree the wiki documentation is way out of date, particularly the getting started guide. I have had improvements planned for quite some time, but just haven't had a chance to finish them. I hope to get to them soon.

I do not understand the language, but the idea of your project is great! If you'd like to contribute documentation back to WALA, let me know and I will try hard to facilitate it.